@nukipa/post-content 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @nukipa/post-content
+
+Framework-agnostic processor for CMS post bodies.
+
+```js
+import { renderPostBody, renderSourcesList } from '@nukipa/post-content';
+
+const { html, mounts } = renderPostBody({
+  body:       post.body,
+  components: post.components,
+  sources:    post.sources,
+  options:    { lang: post.language, postId: post.id }
+});
+```
+
+## What it handles
+
+| Marker / type        | Behaviour                                             |
+| -------------------- | ----------------------------------------------------- |
+| `{{fact}}…{{/fact}}` | Wrapper stripped, inner text kept                     |
+| `{{cite:N}}`         | Replaced with `<sup><a href="#source-N">…` after MD   |
+| `{{component:UUID}}` | Rendered to HTML; interactive types add to `mounts`   |
+| Component types      | callout, faq, steps, card, data_table, comparison, process, image, image_carousel, chart, widget, quote, cta, form, contact_form |
+
+CTAs render as a real `<a href>` (so SEO + no-JS still navigate) plus a
+`data-island="cta"` placeholder — framework adapters attach click tracking
+on top via the `mounts` entry. Lead-gen forms, contact forms, charts,
+carousels, and widgets emit `data-island="..."` placeholders only; the
+adapter is responsible for hydration.
+
+## Class names
+
+All static blocks use `bp-*` classes matching the Vue site at
+`apps/public/`. Lift the relevant CSS rules from
+`apps/public/app/components/BlogArticle.vue` (scoped style block) into
+your tenant site's stylesheet — keys remain stable.
+
+## Peer deps
+
+`marked@^17` — bring your own. The package uses one shared instance
+internally for component-content rendering and the host's instance via
+`renderPostBody` for the outer body.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nukipa/post-content",
+  "version": "0.1.0",
+  "description": "Framework-agnostic processor for Nukipa CMS post bodies — markdown + component markers + citations → HTML + interactive island descriptors.",
+  "license": "MIT",
+  "author": "Nukipa Labs",
+  "homepage": "https://github.com/nukipa-labs/nukipa/tree/main/packages/post-content",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nukipa-labs/nukipa.git",
+    "directory": "packages/post-content"
+  },
+  "bugs": {
+    "url": "https://github.com/nukipa-labs/nukipa/issues"
+  },
+  "keywords": ["nukipa", "cms", "markdown", "post", "renderer"],
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types":  "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": ["src", "README.md"],
+  "peerDependencies": {
+    "marked": "^17.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/components.js

@@ -0,0 +1,386 @@
+// Component registry. One render function per component_type, ported from
+// apps/public/app/utils/postComponents.ts. Class names match (`bp-*`) so
+// CSS lifted from the Vue site keeps working.
+//
+// Each renderer either:
+//   - returns `{ html }` for a static block, or
+//   - returns `{ html, mount }` where `html` carries `data-island="..."`
+//     placeholders and `mount` describes the framework-side hydration.
+//
+// CTA is hybrid: emits a real <a href> for SEO + navigation without JS, plus
+// `data-island="cta"` so a framework adapter can attach click tracking.
+
+import { Marked } from 'marked';
+import { escapeHtml, escapeAttr, safeUrl } from './escape.js';
+
+const innerMarked = new Marked();
+const md       = (text) => (text ? innerMarked.parse(String(text))                      : '');
+const mdInline = (text) => (text ? innerMarked.parseInline(String(text).replace(/\n+/g, ' ')) : '');
+
+// ─── interactive primitives (CTA / form / contact_form) ─────────────────
+
+function renderCta(component) {
+  const content  = component.content || {};
+  const resolved = content._resolved;
+  if (!resolved) return { html: '' };
+
+  const id          = resolved.id || '';
+  const ctaType     = resolved.cta_type || 'url';
+  const styleClass  = resolved.style === 'outline'
+    ? 'cta-outline'
+    : (resolved.style === 'subtle' ? 'cta-subtle' : 'cta-primary');
+  const label       = String(content.label_override       ?? resolved.label       ?? '').trim();
+  const description = String(content.description_override ?? resolved.description ?? '').trim();
+  const url         = safeUrl(resolved.url);
+
+  if (ctaType === 'form') {
+    const attrs = [
+      `data-island="cta-form"`,
+      `data-cta-id="${escapeAttr(id)}"`,
+      label       ? `data-cta-label="${escapeAttr(label)}"`             : '',
+      description ? `data-cta-description="${escapeAttr(description)}"` : ''
+    ].filter(Boolean).join(' ');
+    return {
+      html:  `<div class="inline-contact-form-mount" ${attrs}></div>`,
+      mount: { kind: 'cta-form', id, label, description }
+    };
+  }
+
+  if (!label || url === '#') return { html: '' };
+  const desc = description ? `<p class="inline-cta-description">${escapeHtml(description)}</p>` : '';
+  return {
+    html:
+      `<div class="inline-cta-block" data-island="cta">${desc}` +
+      `<a href="${escapeAttr(url)}" class="inline-cta-btn ${styleClass}" ` +
+      `data-cta-id="${escapeAttr(id)}" data-cta-label="${escapeAttr(label)}" ` +
+      `target="_blank" rel="noopener">${escapeHtml(label)}</a></div>`,
+    mount: { kind: 'cta', id, label, url, postId: null /* filled by caller */ }
+  };
+}
+
+function renderForm(component) {
+  const content = component.content || {};
+  const slug = content.form_slug || content.slug;
+  if (!slug) return { html: '' };
+  const attrs = [
+    `data-island="form"`,
+    `data-form-slug="${escapeAttr(slug)}"`,
+    content.title        ? `data-form-title="${escapeAttr(content.title)}"`               : '',
+    content.description  ? `data-form-description="${escapeAttr(content.description)}"`   : '',
+    content.submit_label ? `data-form-submit-label="${escapeAttr(content.submit_label)}"` : ''
+  ].filter(Boolean).join(' ');
+  return {
+    html: `<div class="lead-form-mount" ${attrs}></div>`,
+    mount: {
+      kind:        'form',
+      slug,
+      title:       content.title        ?? null,
+      description: content.description  ?? null,
+      submitLabel: content.submit_label ?? null
+    }
+  };
+}
+
+function renderContactForm(component) {
+  const content = component.content || {};
+  const payload = {
+    title:           content.title           ?? null,
+    description:     content.description     ?? null,
+    submit_label:    content.submit_label    ?? null,
+    success_message: content.success_message ?? null,
+    fields:          Array.isArray(content.fields) ? content.fields : null
+  };
+  return {
+    html:
+      `<div class="contact-form-mount" data-island="contact-form" ` +
+      `data-component-id="${escapeAttr(component.id)}" ` +
+      `data-content="${escapeAttr(JSON.stringify(payload))}"></div>`,
+    mount: { kind: 'contact-form', componentId: component.id, ...payload }
+  };
+}
+
+// ─── static block components ────────────────────────────────────────────
+
+const CALLOUT_STYLES = {
+  note:      { icon: 'info',      label: 'Note'      },
+  tip:       { icon: 'lightbulb', label: 'Tip'       },
+  important: { icon: 'star',      label: 'Important' },
+  warning:   { icon: 'warning',   label: 'Warning'   },
+  caution:   { icon: 'block',     label: 'Caution'   }
+};
+
+function renderCallout(content) {
+  const level = String(content.level || 'note');
+  const style = CALLOUT_STYLES[level] || CALLOUT_STYLES.note;
+  return {
+    html:
+      `<div class="bp-component bp-callout bp-callout--${escapeAttr(level)}">` +
+      `<div class="bp-callout__header"><span class="material-icons">${escapeHtml(style.icon)}</span> ${escapeHtml(style.label)}</div>` +
+      `<div class="bp-callout__body">${md(content.content)}</div>` +
+      `</div>`
+  };
+}
+
+function renderFaq(content) {
+  const items = (Array.isArray(content.items) ? content.items : []).map((item) =>
+    `<details class="bp-faq-item">` +
+    `<summary><span class="material-icons bp-faq-icon">help_outline</span>` +
+    `<span class="bp-faq-question">${escapeHtml(item?.question)}</span>` +
+    `<span class="material-icons bp-faq-chevron">expand_more</span></summary>` +
+    `<div class="bp-faq-answer">${md(item?.answer)}</div>` +
+    `</details>`
+  ).join('');
+  return { html: `<div class="bp-component bp-faq">${items}</div>` };
+}
+
+function renderSteps(content) {
+  const list = Array.isArray(content.items) ? content.items : [];
+  const total = list.length;
+  const items = list.map((item, i) =>
+    `<div class="bp-step${i === total - 1 ? ' bp-step--last' : ''}">` +
+    `<div class="bp-step__marker">` +
+    `<span class="bp-step__num">${i + 1}</span>` +
+    (i < total - 1 ? '<span class="bp-step__line"></span>' : '') +
+    `</div>` +
+    `<div class="bp-step__content">` +
+    `<strong>${escapeHtml(item?.title)}</strong>` +
+    `<p>${mdInline(item?.description)}</p>` +
+    `</div></div>`
+  ).join('');
+  return { html: `<div class="bp-component bp-steps">${items}</div>` };
+}
+
+function renderCard(content) {
+  const img = content.image_url ? `<img src="${escapeAttr(content.image_url)}" alt="" class="bp-card__img" />` : '';
+  return {
+    html:
+      `<div class="bp-component bp-card">${img}` +
+      `<div class="bp-card__body">` +
+      `<div class="bp-card__title">${escapeHtml(content.title)}</div>` +
+      md(content.content) +
+      `</div></div>`
+  };
+}
+
+function renderDataTable(content) {
+  const cols = Array.isArray(content.columns) ? content.columns : [];
+  const rows = Array.isArray(content.rows)    ? content.rows    : [];
+  const thead = cols.map((c) => `<th>${escapeHtml(typeof c === 'string' ? c : c?.label)}</th>`).join('');
+  const tbody = rows.map((row) => {
+    if (Array.isArray(row)) {
+      return `<tr>${row.map((cell) => `<td>${escapeHtml(String(cell))}</td>`).join('')}</tr>`;
+    }
+    return `<tr>${cols.map((c) => `<td>${escapeHtml(String(row?.[typeof c === 'string' ? c : c?.key] ?? ''))}</td>`).join('')}</tr>`;
+  }).join('');
+  return {
+    html:
+      `<div class="bp-component bp-data-table">` +
+      (content.title ? `<div class="bp-data-table__title">${escapeHtml(content.title)}</div>` : '') +
+      `<table><thead><tr>${thead}</tr></thead><tbody>${tbody}</tbody></table>` +
+      `</div>`
+  };
+}
+
+function renderComparison(content) {
+  const rawCols = Array.isArray(content.columns) ? content.columns : [];
+  const rawRows = Array.isArray(content.rows)    ? content.rows    : [];
+
+  // The comparison schema spec is `columns: ["Feature", "Us", "Them"]` (string
+  // array) and `rows: [["row1col1", "row1col2", ...]]` (array of arrays).
+  // The writer LLM occasionally emits the data_table shape instead — column
+  // objects (`{key, label}`) plus row OBJECTS keyed by column.key. We
+  // detect that shape and project it into the canonical form rather than
+  // string-coercing the objects (which renders as "[object Object]").
+  const looksLikeDataTable = rawCols.length > 0
+    && rawCols.every((c) => c && typeof c === 'object')
+    && (rawCols[0].label !== undefined || rawCols[0].key !== undefined || rawCols[0].title !== undefined);
+
+  let cols;
+  let rows;
+  if (looksLikeDataTable) {
+    cols = rawCols.map((c) => c.label ?? c.title ?? c.key ?? '');
+    const keys = rawCols.map((c) => c.key ?? c.label ?? c.title ?? '');
+    rows = rawRows.map((row) => {
+      // Accept both object-form (keyed by column.key) and array-form rows
+      // mixed inside the same component — the LLM is occasionally
+      // inconsistent. Arrays still pass through positionally.
+      if (row && typeof row === 'object' && !Array.isArray(row)) {
+        return keys.map((k) => row[k] ?? '');
+      }
+      return Array.isArray(row) ? row : [];
+    });
+  } else {
+    cols = rawCols.map((c) => (c && typeof c === 'object' ? (c.label ?? c.title ?? c.key ?? '') : c));
+    rows = rawRows.map((row) => (Array.isArray(row) ? row : []));
+  }
+
+  const thead = cols.map((c) => `<th>${escapeHtml(String(c))}</th>`).join('');
+  const tbody = rows.map((row) =>
+    `<tr>${row.map((cell, i) =>
+      `<td${i === 0 ? '' : ' class="bp-comparison__cell"'}>${escapeHtml(String(cell ?? ''))}</td>`
+    ).join('')}</tr>`
+  ).join('');
+  return {
+    html:
+      `<div class="bp-component bp-comparison">` +
+      `<table><thead><tr>${thead}</tr></thead><tbody>${tbody}</tbody></table>` +
+      `</div>`
+  };
+}
+
+function renderProcess(content) {
+  const list = Array.isArray(content.items) ? content.items : [];
+  const total = list.length;
+  const items = list.map((item, i) =>
+    `<div class="bp-process__stage">` +
+    `<div class="bp-process__icon">${item?.icon
+      ? `<span class="material-icons">${escapeHtml(item.icon)}</span>`
+      : `<span class="bp-process__num">${i + 1}</span>`}</div>` +
+    `<div class="bp-process__title">${escapeHtml(item?.title)}</div>` +
+    (item?.description ? `<div class="bp-process__desc">${escapeHtml(item.description)}</div>` : '') +
+    `</div>` +
+    (i < total - 1
+      ? '<div class="bp-process__connector"><span class="material-icons">arrow_forward</span></div>'
+      : '')
+  ).join('');
+  return { html: `<div class="bp-component bp-process">${items}</div>` };
+}
+
+function renderImage(component) {
+  const content = component.content || {};
+  const status  = String(content.status || '').toLowerCase();
+  if (status === 'pending' || status === 'generating') {
+    return { html: `<div class="bp-image-placeholder">Generating image…</div>` };
+  }
+  const url = typeof content.url === 'string' ? content.url.trim() : '';
+  if (!url || status === 'error') return { html: '' };
+
+  const alt        = String(content.alt ?? '');
+  const captionRaw = content.caption ? String(content.caption) : '';
+  const caption    = captionRaw ? `<figcaption class="bp-image__caption">${md(captionRaw)}</figcaption>` : '';
+
+  let credit = '';
+  const attr = content.attribution;
+  if (attr && typeof attr === 'object') {
+    const author     = typeof attr.author     === 'string' ? attr.author.trim()     : '';
+    const source     = typeof attr.source     === 'string' ? attr.source.trim()     : '';
+    const sourceUrl  = typeof attr.source_url === 'string' ? attr.source_url.trim() : '';
+    const safeSrcUrl = (sourceUrl.startsWith('http://') || sourceUrl.startsWith('https://')) ? sourceUrl : '';
+    const labelParts = [author, source].filter(Boolean);
+    if (labelParts.length > 0) {
+      const label = escapeHtml(labelParts.join(' / '));
+      const inner = safeSrcUrl
+        ? `<a href="${escapeAttr(safeSrcUrl)}" target="_blank" rel="noopener nofollow">${label}</a>`
+        : label;
+      credit = `<small class="bp-image__credit">Photo: ${inner}</small>`;
+    }
+  }
+
+  return {
+    html:
+      `<figure class="bp-component bp-image" data-component-id="${escapeAttr(component.id)}">` +
+      `<img src="${escapeAttr(url)}" alt="${escapeAttr(alt)}" loading="lazy" />` +
+      caption + credit +
+      `</figure>`
+  };
+}
+
+function renderImageCarousel(content) {
+  const list = Array.isArray(content.items) ? content.items : [];
+  const items = list.map((item, i) =>
+    `<div class="bp-carousel__slide${i === 0 ? ' active' : ''}">` +
+    `<img src="${escapeAttr(item?.image_url)}" alt="${escapeAttr(item?.alt || '')}" />` +
+    (item?.caption ? `<div class="bp-carousel__caption">${escapeHtml(item.caption)}</div>` : '') +
+    `</div>`
+  ).join('');
+  return {
+    html:
+      `<div class="bp-component bp-carousel" data-island="carousel" data-carousel>` +
+      `<div class="bp-carousel__track">${items}</div>` +
+      `<button class="bp-carousel__prev" data-carousel-prev><span class="material-icons">chevron_left</span></button>` +
+      `<button class="bp-carousel__next" data-carousel-next><span class="material-icons">chevron_right</span></button>` +
+      `</div>`,
+    mount: { kind: 'carousel' }
+  };
+}
+
+function renderChart(content) {
+  const title = content.title ? `<div class="bp-chart__title">${escapeHtml(content.title)}</div>` : '';
+  const encoded = escapeAttr(JSON.stringify({
+    type:    content.chart_type,
+    data:    content.data,
+    options: content.options
+  }));
+  return {
+    html:
+      `<div class="bp-component bp-chart" data-island="chart" data-chart="${encoded}">` +
+      title +
+      `<canvas class="bp-chart__canvas" width="600" height="300"></canvas>` +
+      `</div>`,
+    mount: { kind: 'chart', chartType: content.chart_type, data: content.data, options: content.options, title: content.title || null }
+  };
+}
+
+function renderWidget(component, opts) {
+  const content = component.content || {};
+  const status  = String(content.status || 'pending');
+  const ready   = status === 'ready' && typeof content.html_content === 'string' && content.html_content.length > 0;
+
+  if (ready) {
+    const lang = (opts?.lang || 'en').split('-')[0];
+    return {
+      html:
+        `<div class="bp-component bp-widget">` +
+        `<div class="inline-widget-container" data-island="widget" ` +
+        `data-widget-id="${escapeAttr(component.id)}" ` +
+        `data-widget-lang="${escapeAttr(lang)}"></div>` +
+        `</div>`,
+      mount: { kind: 'widget', componentId: component.id, html: content.html_content, lang }
+    };
+  }
+
+  let message = 'Widget generating...';
+  if (status === 'pending')    message = 'Widget queued for generation...';
+  if (status === 'generating') message = 'Widget generating...';
+  if (status === 'error')      message = 'Widget generation failed';
+  return {
+    html:
+      `<div class="bp-component bp-widget-placeholder bp-widget-placeholder--${escapeAttr(status)}">` +
+      escapeHtml(message) +
+      `</div>`
+  };
+}
+
+function renderQuote(content) {
+  const cite = content.cite ? `<cite class="bp-quote__cite">${escapeHtml(content.cite)}</cite>` : '';
+  return {
+    html: `<blockquote class="bp-component bp-quote">${md(content.content)}${cite}</blockquote>`
+  };
+}
+
+const RENDERERS = {
+  cta:            (c) => renderCta(c),
+  form:           (c) => renderForm(c),
+  contact_form:   (c) => renderContactForm(c),
+  callout:        (c) => renderCallout(c.content || {}),
+  faq:            (c) => renderFaq(c.content || {}),
+  steps:          (c) => renderSteps(c.content || {}),
+  card:           (c) => renderCard(c.content || {}),
+  data_table:     (c) => renderDataTable(c.content || {}),
+  comparison:     (c) => renderComparison(c.content || {}),
+  process:        (c) => renderProcess(c.content || {}),
+  image:          (c) => renderImage(c),
+  image_carousel: (c) => renderImageCarousel(c.content || {}),
+  chart:          (c) => renderChart(c.content || {}),
+  widget:         (c, opts) => renderWidget(c, opts),
+  quote:          (c) => renderQuote(c.content || {})
+};
+
+/**
+ * Render a single component to `{ html, mount? }`. Unknown types produce
+ * empty html — the marker drops, surrounding markdown stays clean.
+ */
+export function renderComponent(component, opts = {}) {
+  const fn = RENDERERS[component?.component_type];
+  return fn ? fn(component, opts) : { html: '' };
+}

package/src/escape.js

@@ -0,0 +1,19 @@
+// Tiny HTML/attr escape used by the component renderers. Same shape as the
+// Vue renderer at apps/public/app/utils/postComponents.ts so styles port.
+
+export function escapeHtml(s) {
+  return String(s ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+export const escapeAttr = escapeHtml;
+
+const SAFE_URL_RE = /^(https?:\/\/|\/|mailto:|tel:|#)/i;
+export function safeUrl(u) {
+  const s = String(u ?? '').trim();
+  return SAFE_URL_RE.test(s) ? s : '#';
+}

package/src/index.d.ts

@@ -0,0 +1,50 @@
+// Type declarations for @nukipa/post-content.
+
+export interface PostComponent {
+  id:             string;
+  component_type: string;
+  content:        Record<string, unknown>;
+}
+
+export interface PostSource {
+  idx:    number;
+  title?: string | null;
+  url?:   string | null;
+}
+
+export interface RenderOpts {
+  lang?:   string;
+  postId?: string | null;
+}
+
+export type Mount =
+  | { kind: 'cta';          id: string;  label: string; url: string; postId: string | null }
+  | { kind: 'cta-form';     id: string;  label: string; description: string }
+  | { kind: 'form';         slug: string; title: string | null; description: string | null; submitLabel: string | null }
+  | { kind: 'contact-form'; componentId: string; title: string | null; description: string | null; submit_label: string | null; success_message: string | null; fields: Array<Record<string, unknown>> | null }
+  | { kind: 'carousel' }
+  | { kind: 'chart';        chartType: string; data: unknown; options: unknown; title: string | null }
+  | { kind: 'widget';       componentId: string; html: string; lang: string };
+
+export interface RenderPostBodyInput {
+  body:        string;
+  components?: PostComponent[];
+  sources?:    PostSource[];
+  options?:    RenderOpts;
+}
+
+export interface RenderPostBodyResult {
+  html:   string;
+  mounts: Mount[];
+}
+
+export function renderPostBody(input: RenderPostBodyInput): RenderPostBodyResult;
+export function renderComponent(component: PostComponent, opts?: RenderOpts): { html: string; mount?: Mount };
+export function renderSourcesList(sources: PostSource[]): string;
+export function stripFactMarkers(markdown: string): string;
+export function applyCiteMarkers(html: string, sourceCount: number): string;
+export function substituteComponentMarkers(
+  markdown: string,
+  components?: PostComponent[],
+  options?: RenderOpts
+): string;

package/src/index.js

@@ -0,0 +1,94 @@
+// Public entry point for @nukipa/post-content.
+//
+// One main function: `renderPostBody({ body, components, sources, options })`.
+// Returns `{ html, mounts }` — the processed HTML and a list of interactive
+// island descriptors to hydrate framework-side.
+
+import { marked } from 'marked';
+import {
+  stripFactMarkers,
+  substituteComponentMarkers as substituteCore,
+  applyCiteMarkers
+} from './markers.js';
+import { renderComponent } from './components.js';
+
+export { renderComponent } from './components.js';
+export { stripFactMarkers, applyCiteMarkers } from './markers.js';
+
+/**
+ * Convenience wrapper: takes the raw `components` array (as the CMS returns
+ * it) and renders the markers in-place using the package's component
+ * registry. Returns the substituted markdown only — callers that need the
+ * `mounts` list should use `renderPostBody` instead.
+ *
+ * Mirrors the legacy `apps/public/app/utils/postComponents.ts#substituteComponentMarkers`
+ * shape so existing call sites can drop the local file in favour of this.
+ */
+export function substituteComponentMarkers(markdown, components = [], options = {}) {
+  const byId = new Map((components || []).map((c) => [c.id, c]));
+  const { markdown: out } = substituteCore(
+    markdown,
+    byId,
+    (component) => renderComponent(component, options)
+  );
+  return out;
+}
+
+/**
+ * Process a CMS post body.
+ *
+ * Pipeline:
+ *   1. Strip `{{fact}}…{{/fact}}` wrappers (keep the inner text).
+ *   2. Substitute `{{component:UUID}}` markers — emit HTML and collect
+ *      `mounts` for interactive components.
+ *   3. Run marked with GFM enabled.
+ *   4. Replace `{{cite:N}}` superscripts against the sources list.
+ */
+export function renderPostBody({ body, components = [], sources = [], options = {} }) {
+  const stripped = stripFactMarkers(body);
+  const byId     = new Map((components || []).map((c) => [c.id, c]));
+
+  const { markdown: substituted, mounts } = substituteCore(
+    stripped,
+    byId,
+    (component) => renderComponent(component, options)
+  );
+
+  // Annotate `cta` mounts with the post id so the framework adapter can
+  // pass it through to the click-tracking endpoint — the renderer doesn't
+  // have it directly.
+  const postId = options.postId ?? null;
+  for (const m of mounts) {
+    if (m.kind === 'cta') m.postId = postId;
+  }
+
+  const rawHtml = marked.parse(substituted, { gfm: true, breaks: false });
+  const html    = applyCiteMarkers(typeof rawHtml === 'string' ? rawHtml : '', (sources || []).length);
+
+  return { html, mounts };
+}
+
+/**
+ * Render the sources list as `<ol>` matching the `#source-N` anchors that
+ * `applyCiteMarkers` emits. Caller chooses where to place it (typically at
+ * the foot of the article).
+ */
+export function renderSourcesList(sources) {
+  if (!Array.isArray(sources) || sources.length === 0) return '';
+  const items = sources.map((s) => {
+    const idx   = s.idx;
+    const title = s.title ? String(s.title) : (s.url ? String(s.url) : `Source ${idx}`);
+    const safe  = (s.url && /^https?:\/\//.test(s.url))
+      ? `<a href="${s.url}" target="_blank" rel="noopener nofollow">${escape(title)}</a>`
+      : escape(title);
+    return `<li id="source-${idx}">${safe}</li>`;
+  }).join('');
+  return `<ol class="bp-sources">${items}</ol>`;
+}
+
+function escape(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}

package/src/markers.js

@@ -0,0 +1,76 @@
+// Marker handling for CMS post bodies.
+//
+// CMS bodies are markdown that may contain three classes of marker:
+//
+//   {{component:UUID}}   — substituted with rendered HTML before marked.
+//   {{cite:N}}           — replaced with footnote-style anchors after marked.
+//   {{fact}}…{{/fact}}   — wraps a claim that the LLM marked as load-bearing.
+//                          The public renderer keeps the inner text and drops
+//                          the wrapper. (Editorial review uses the marker; the
+//                          public site doesn't.)
+
+const FACT_OPEN_RE  = /\{\{\s*fact\s*\}\}/gi;
+const FACT_CLOSE_RE = /\{\{\s*\/\s*fact\s*\}\}/gi;
+const COMPONENT_RE  = /\{\{component:([a-f0-9-]+)\}\}/gi;
+const CITE_RE       = /\{\{\s*cite:(\d+)\s*\}\}/g;
+
+/** Strip `{{fact}}…{{/fact}}` wrappers, keeping the inner text. */
+export function stripFactMarkers(markdown) {
+  if (!markdown) return '';
+  return String(markdown)
+    .replace(FACT_OPEN_RE,  '')
+    .replace(FACT_CLOSE_RE, '');
+}
+
+/**
+ * Substitute every `{{component:UUID}}` marker with its rendered HTML.
+ * Run BEFORE marked.parse so the emitted HTML isn't wrapped in <p>.
+ *
+ * @param {string} markdown
+ * @param {{render: (component: object) => {html: string, mount?: object}}} opts
+ *   `render` returns the HTML for the substituted block plus an optional
+ *   `mount` descriptor — populated when the component is interactive (the
+ *   placeholder needs framework-side hydration).
+ * @param {Map<string, object>} byId — components keyed by id.
+ * @returns {{markdown: string, mounts: object[]}}
+ */
+export function substituteComponentMarkers(markdown, byId, render) {
+  const mounts = [];
+  if (!markdown) return { markdown: '', mounts };
+  if (byId.size === 0) {
+    return { markdown: String(markdown).replace(COMPONENT_RE, ''), mounts };
+  }
+  const out = String(markdown).replace(COMPONENT_RE, (_match, id) => {
+    const comp = byId.get(id);
+    if (!comp) return '';
+    const { html, mount } = render(comp) || { html: '' };
+    if (mount) mounts.push(mount);
+    return html ? `\n\n${compactInlineHtml(html)}\n\n` : '';
+  });
+  return { markdown: out, mounts };
+}
+
+/**
+ * Replace `{{cite:N}}` with footnote-style superscripts. Run AFTER marked
+ * since cite markers often live inside paragraphs / lists. Markers whose
+ * `N` has no matching source render as plain `[N]` so data isn't lost.
+ */
+export function applyCiteMarkers(html, sourceCount) {
+  if (!html) return '';
+  return String(html).replace(CITE_RE, (_match, n) => {
+    const idx = Number(n);
+    if (!Number.isFinite(idx) || idx < 1) return '';
+    const valid = sourceCount > 0 && idx <= sourceCount;
+    return valid
+      ? `<sup class="bp-cite"><a href="#source-${idx}" data-source-idx="${idx}">[${idx}]</a></sup>`
+      : `<sup class="bp-cite bp-cite--orphan">[${idx}]</sup>`;
+  });
+}
+
+// Collapse whitespace BETWEEN tags so multi-line render strings produce a
+// single HTML block. Without this, marked treats indented blank lines
+// inside the HTML as code-block boundaries — see the Vue version's comment
+// at apps/public/app/utils/postComponents.ts:457 for the failure mode.
+function compactInlineHtml(html) {
+  return String(html).replace(/\n[ \t]*/g, '');
+}