ferst-core 0.2.9 → 0.4.0

package/components/BlockRenderer.astro

@@ -42,6 +42,8 @@ import MapEmbed from './recipes/MapEmbed.astro';
 import Table from './recipes/Table.astro';
 import Notice from './recipes/Notice.astro';
 import MediaCards from './recipes/MediaCards.astro';
+import ContactCard from './recipes/ContactCard.astro';
+import Locations from './recipes/Locations.astro';
 
 interface Props {
   blocks: Block[];
@@ -86,6 +88,8 @@ const registry: Record<BlockType, any> = {
   table: Table,
   notice: Notice,
   mediaCards: MediaCards,
+  contactCard: ContactCard,
+  locations: Locations,
 };
 ---
 

package/components/CalendarEmbed.astro

@@ -76,42 +76,53 @@ const safe = isSafeEmbedUrl(finalEmbedUrl);
 </section>
 
 <script>
-  // Bundled (not is:inline), so it runs once even with multiple calendars on a
-  // page. Wires each embed's consent gate; auto-loads where consent was given.
-  const CONSENT_KEY = 'ferst-calendar-consent';
-  document.querySelectorAll<HTMLElement>('.b-calendar__embed').forEach((el) => {
+  // Bundled (runs once even with multiple calendars on a page). Consent is the
+  // shared site-wide embed consent: accepting the cookie banner (or the footer
+  // panel) auto-loads every embed. The per-embed button is a fallback that grants
+  // the same consent, so one click still loads everything and is remembered.
+  import { hasConsent, setConsent, onConsentChange } from '../lib/consent-client';
+
+  const embeds = document.querySelectorAll<HTMLElement>('.b-calendar__embed');
+
+  // Best-effort theme blend: Google Calendar embeds expose only `bgcolor` (the
+  // surround), not a real dark mode — the grid stays Google's own light. We match
+  // the surround to the current theme surface so the frame doesn't sit as a hard
+  // block. Resolved from --bg-surface at load (a later theme toggle keeps it).
+  function themedCalendarUrl(url: string): string {
+    if (!/google\.com\/calendar|calendar\.google\.com/.test(url)) return url;
+    const probe = document.createElement('span');
+    probe.style.cssText = 'display:none;background:var(--bg-surface)';
+    document.body.appendChild(probe);
+    const m = getComputedStyle(probe).backgroundColor.match(/\d+/g);
+    probe.remove();
+    if (!m) return url;
+    const hex = m.slice(0, 3).map((n) => (+n).toString(16).padStart(2, '0')).join('');
+    return url + (url.includes('?') ? '&' : '?') + 'bgcolor=%23' + hex;
+  }
+
+  function load(el: HTMLElement) {
+    if (el.dataset.loaded === 'true') return;
     const url = el.dataset.embedUrl;
-    if (!url) return;
-    const height = el.dataset.height || '600';
-    const title = el.dataset.title || 'Calendar';
     const frameSlot = el.querySelector<HTMLElement>('.b-calendar__frame');
+    if (!url || !frameSlot) return;
+    const frame = document.createElement('iframe');
+    frame.src = themedCalendarUrl(url);
+    frame.title = el.dataset.title || 'Calendar';
+    frame.loading = 'lazy';
+    frame.style.width = '100%';
+    frame.style.height = (el.dataset.height || '600') + 'px';
+    frame.style.border = '0';
+    frameSlot.replaceChildren(frame);
+    el.dataset.loaded = 'true';
     const consent = el.querySelector<HTMLElement>('.b-calendar__consent');
-    const btn = el.querySelector<HTMLButtonElement>('.b-calendar__load');
-
-    function load() {
-      if (el.dataset.loaded === 'true' || !frameSlot) return;
-      const frame = document.createElement('iframe');
-      frame.src = url as string;
-      frame.title = title;
-      frame.loading = 'lazy';
-      frame.style.width = '100%';
-      frame.style.height = height + 'px';
-      frame.style.border = '0';
-      frameSlot.replaceChildren(frame);
-      el.dataset.loaded = 'true';
-      if (consent) consent.hidden = true;
-    }
-
-    try {
-      if (localStorage.getItem(CONSENT_KEY) === '1') load();
-    } catch (_) {}
+    if (consent) consent.hidden = true;
+  }
+  const loadAll = () => embeds.forEach(load);
 
-    btn?.addEventListener('click', () => {
-      try {
-        localStorage.setItem(CONSENT_KEY, '1');
-      } catch (_) {}
-      load();
-    });
+  if (hasConsent()) loadAll();
+  onConsentChange((allowed) => { if (allowed) loadAll(); });
+  embeds.forEach((el) => {
+    el.querySelector<HTMLButtonElement>('.b-calendar__load')?.addEventListener('click', () => setConsent(true));
   });
 </script>
 

package/components/CookieBanner.astro

@@ -0,0 +1,126 @@
+---
+/**
+ * CookieBanner — the site's single cookie consent prompt, shown once on the first
+ * visit until the visitor chooses. Accepting lets embedded third-party content
+ * (Google Calendar, Google Maps) load automatically wherever it appears — no
+ * separate per-embed gate. The footer's "Cookie preferences" panel lets them
+ * change their mind later. Site chrome, rendered by Base after the page.
+ *
+ * Hidden by default; the client script reveals it only when no choice is stored,
+ * so it never flashes for returning visitors.
+ */
+interface Props {
+  /** Link to the cookie policy page (omit to hide the link). */
+  policyHref?: string;
+}
+const { policyHref = '/cookie-policy/' } = Astro.props;
+---
+
+<div class="cookie-banner" id="cookie-banner" role="dialog" aria-label="Cookie notice" aria-live="polite" hidden>
+  <p class="cookie-banner__text">
+    We use a few cookies to run the site and to show embedded content like our
+    calendar and maps.{policyHref && (<> See our <a href={policyHref}>cookie policy</a>.</>)}
+  </p>
+  <div class="cookie-banner__actions">
+    <button type="button" class="cookie-banner__btn cookie-banner__btn--ghost" id="cookie-banner-decline">Decline</button>
+    <button type="button" class="cookie-banner__btn cookie-banner__btn--primary" id="cookie-banner-accept">Accept</button>
+  </div>
+</div>
+
+<script>
+  import { isDecided, setConsent } from '../lib/consent-client';
+
+  const banner = document.getElementById('cookie-banner');
+  if (banner && !isDecided()) {
+    banner.hidden = false;
+    // Next frame so the entry transition runs.
+    requestAnimationFrame(() => banner.classList.add('visible'));
+  }
+
+  function dismiss(granted: boolean) {
+    setConsent(granted);
+    banner?.classList.remove('visible');
+    if (banner) setTimeout(() => { banner.hidden = true; }, 400);
+  }
+
+  document.getElementById('cookie-banner-accept')?.addEventListener('click', () => dismiss(true));
+  document.getElementById('cookie-banner-decline')?.addEventListener('click', () => dismiss(false));
+</script>
+
+<style is:global>
+  .cookie-banner {
+    position: fixed;
+    left: 20px;
+    right: 20px;
+    bottom: 20px;
+    z-index: 210;
+    max-width: 40rem;
+    margin-inline: auto;
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.75rem 1.25rem;
+    padding: 1rem 1.2rem;
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: 14px;
+    box-shadow: 0 16px 40px rgba(0, 0, 0, 0.18);
+    transform: translateY(12px);
+    opacity: 0;
+    transition: transform 0.4s cubic-bezier(0.16, 1, 0.3, 1), opacity 0.4s ease;
+  }
+  .cookie-banner.visible {
+    transform: translateY(0);
+    opacity: 1;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .cookie-banner { transition: opacity 0.2s ease; transform: none; }
+  }
+  .cookie-banner__text {
+    margin: 0;
+    flex: 1 1 18rem;
+    min-width: 0;
+    font-family: var(--font-body);
+    font-size: 0.85rem;
+    line-height: 1.55;
+    color: var(--muted);
+  }
+  .cookie-banner__text a {
+    color: var(--muted);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+  }
+  .cookie-banner__text a:hover { color: var(--fg); }
+  .cookie-banner__actions {
+    display: flex;
+    gap: 0.6rem;
+    flex-shrink: 0;
+  }
+  .cookie-banner__btn {
+    font: inherit;
+    font-family: var(--font-heading);
+    font-size: 0.85rem;
+    font-weight: 600;
+    padding: 0.5rem 1.1rem;
+    border-radius: var(--radius-sm);
+    cursor: pointer;
+    transition: filter 0.15s ease, background 0.15s ease, color 0.15s ease;
+  }
+  .cookie-banner__btn--primary {
+    border: none;
+    background: var(--gold);
+    color: var(--text-light);
+  }
+  .cookie-banner__btn--primary:hover { filter: brightness(0.94); }
+  .cookie-banner__btn--ghost {
+    border: 1px solid var(--border);
+    background: transparent;
+    color: var(--fg);
+  }
+  .cookie-banner__btn--ghost:hover { background: var(--bg-section); }
+  .cookie-banner__btn:focus-visible {
+    outline: 2px solid var(--gold);
+    outline-offset: 2px;
+  }
+</style>

package/components/CookiePreferences.astro

@@ -29,16 +29,16 @@
 
   <div class="cookie-prefs__row">
     <div class="cookie-prefs__row-text">
-      <p class="cookie-prefs__row-title">Google Calendar</p>
-      <p class="cookie-prefs__row-desc">Loads the embedded calendar on the <a href="/calendar/">Calendar</a> page. Google may set its own cookies once it's loaded.</p>
+      <p class="cookie-prefs__row-title">Embedded content</p>
+      <p class="cookie-prefs__row-desc">Lets our <a href="/calendar/">calendar</a> and maps load from Google. Google may set its own cookies once loaded.</p>
     </div>
     <button
       type="button"
       class="cookie-prefs__switch"
-      id="cookie-prefs-calendar-toggle"
+      id="cookie-prefs-embed-toggle"
       role="switch"
       aria-checked="false"
-      aria-label="Allow Google Calendar embed"
+      aria-label="Allow embedded content (maps and calendar)"
     >
       <span class="cookie-prefs__switch-thumb"></span>
     </button>
@@ -197,15 +197,14 @@
 </style>
 
 <script>
-  const CALENDAR_KEY = 'calendar-consent';
+  import { hasConsent, setConsent, onConsentChange } from '../lib/consent-client';
 
   const panel = document.getElementById('cookie-prefs') as HTMLElement;
   const closeBtn = document.getElementById('cookie-prefs-close') as HTMLButtonElement;
-  const calendarToggle = document.getElementById('cookie-prefs-calendar-toggle') as HTMLButtonElement;
+  const embedToggle = document.getElementById('cookie-prefs-embed-toggle') as HTMLButtonElement;
 
   function syncToggle() {
-    const allowed = localStorage.getItem(CALENDAR_KEY) === '1';
-    calendarToggle.setAttribute('aria-checked', String(allowed));
+    embedToggle.setAttribute('aria-checked', String(hasConsent()));
   }
 
   function open() {
@@ -217,13 +216,14 @@
     panel.classList.remove('visible');
   }
 
-  calendarToggle.addEventListener('click', () => {
-    const next = calendarToggle.getAttribute('aria-checked') !== 'true';
-    calendarToggle.setAttribute('aria-checked', String(next));
-    localStorage.setItem(CALENDAR_KEY, next ? '1' : '0');
-    document.dispatchEvent(new CustomEvent('calendar-consent-changed', { detail: { allowed: next } }));
+  embedToggle.addEventListener('click', () => {
+    setConsent(embedToggle.getAttribute('aria-checked') !== 'true');
+    syncToggle();
   });
 
+  // Keep the switch in sync if consent changes elsewhere (e.g. the banner).
+  onConsentChange(syncToggle);
+
   closeBtn.addEventListener('click', close);
   document.addEventListener('keydown', (e) => {
     if (e.key === 'Escape' && panel.classList.contains('visible')) close();

package/components/PostCard.astro

@@ -12,8 +12,14 @@ interface Props {
   heroImage?: string;
   /** Optional tag labels shown as a small eyebrow. */
   tagLabels?: string[];
+  /** Open the link in a new tab (e.g. a post that's just an attached PDF). */
+  newTab?: boolean;
+  /** The call-to-action label (default "Read more"). */
+  moreLabel?: string;
 }
-const { href, title, date, summary, heroImage, tagLabels = [] } = Astro.props;
+const { href, title, date, summary, heroImage, tagLabels = [], newTab = false, moreLabel = 'Read more' } = Astro.props;
+const linkRel = newTab ? 'noopener' : undefined;
+const linkTarget = newTab ? '_blank' : undefined;
 const d = date instanceof Date ? date : new Date(date);
 const iso = Number.isNaN(d.valueOf()) ? undefined : d.toISOString().slice(0, 10);
 const display = Number.isNaN(d.valueOf())
@@ -23,7 +29,7 @@ const display = Number.isNaN(d.valueOf())
 
 <article class="b-post-card">
   {heroImage && (
-    <a class="b-post-card__media" href={href} tabindex="-1" aria-hidden="true">
+    <a class="b-post-card__media" href={href} target={linkTarget} rel={linkRel} tabindex="-1" aria-hidden="true">
       <img src={heroImage} alt="" loading="lazy" />
     </a>
   )}
@@ -33,10 +39,10 @@ const display = Number.isNaN(d.valueOf())
       {display && <time datetime={iso}>{display}</time>}
     </div>
     <h3 class="b-post-card__title">
-      <a href={href}>{title}</a>
+      <a href={href} target={linkTarget} rel={linkRel}>{title}</a>
     </h3>
     {summary && <p class="b-post-card__summary">{summary}</p>}
-    <span class="b-post-card__more" aria-hidden="true">Read more</span>
+    <span class="b-post-card__more" aria-hidden="true">{moreLabel}</span>
   </div>
 </article>
 

package/components/recipes/ContactCard.astro

@@ -0,0 +1,145 @@
+---
+/**
+ * ContactCard — a Level-2 recipe: a rich, branded "get in touch" band. A gradient
+ * panel (anchored on --ink so it stays a deep, warm brand tone in BOTH themes)
+ * carries a display-type title + a subtitle on the left, the contact channels as
+ * tappable pills on the right, and a closing note across the bottom. For a contact
+ * or find-us page — the polished alternative to a plain notice box.
+ *
+ * Token-driven: the gradient is --ink → brand-tinted, pills are translucent
+ * recesses on it, icons + hovers use --gold, so a CMS colour change recolours the
+ * whole band. Whole pill links when `href` is set.
+ */
+import Icon from '../Icon.astro';
+import { isIconKey } from '../../lib/icons';
+
+interface Item {
+  icon?: string;
+  value: string;
+  href?: string;
+}
+interface Props {
+  eyebrow?: string;
+  title: string;
+  subtitle?: string;
+  note?: string;
+  items?: Item[];
+}
+const { eyebrow, title, subtitle, note, items = [] } = Astro.props;
+const rel = (href?: string) => (href && /^https?:\/\//.test(href) ? 'noopener' : undefined);
+const target = (href?: string) => (href && /^https?:\/\//.test(href) ? '_blank' : undefined);
+---
+
+<section class="b-contact">
+  <div class="b-contact__panel">
+    <div class="b-contact__head">
+      {eyebrow && <p class="b-contact__eyebrow">{eyebrow}</p>}
+      <h2 class="b-contact__title">{title}</h2>
+      {subtitle && <p class="b-contact__subtitle">{subtitle}</p>}
+    </div>
+
+    {items.length > 0 && (
+      <ul class="b-contact__items">
+        {items.map((item) => {
+          const inner = (
+            <>
+              {item.icon && isIconKey(item.icon) && (
+                <span class="b-contact__icon" aria-hidden="true"><Icon name={item.icon} size={18} /></span>
+              )}
+              <span class="b-contact__value">{item.value}</span>
+            </>
+          );
+          return (
+            <li>
+              {item.href ? (
+                <a class="b-contact__item" href={item.href} target={target(item.href)} rel={rel(item.href)}>{inner}</a>
+              ) : (
+                <div class="b-contact__item">{inner}</div>
+              )}
+            </li>
+          );
+        })}
+      </ul>
+    )}
+
+    {note && <p class="b-contact__note">{note}</p>}
+  </div>
+</section>
+
+<style>
+  .b-contact {
+    max-width: 72rem;
+    margin-inline: auto;
+    padding-inline: 1rem;
+  }
+  /* Anchored on --ink (a source colour that stays dark in both themes) so the band
+     reads as a deep, warm brand panel regardless of light/dark. */
+  .b-contact__panel {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 1.5rem 2.5rem;
+    padding: clamp(1.75rem, 4vw, 3rem);
+    border-radius: var(--radius);
+    background: linear-gradient(135deg, var(--ink), color-mix(in srgb, var(--gold) 26%, var(--ink)));
+    color: var(--text-light);
+    box-shadow: var(--shadow-md);
+  }
+  @media (min-width: 48rem) {
+    .b-contact__panel { grid-template-columns: 1.25fr 1fr; align-items: center; }
+  }
+  .b-contact__head { display: flex; flex-direction: column; gap: 0.5rem; }
+  .b-contact__eyebrow {
+    margin: 0;
+    font-family: var(--font-heading);
+    font-size: 0.75rem; font-weight: 700; letter-spacing: 0.14em; text-transform: uppercase;
+    color: color-mix(in srgb, var(--text-light) 70%, transparent);
+  }
+  .b-contact__title {
+    margin: 0;
+    font-family: var(--font-display, var(--font-heading));
+    font-size: clamp(1.9rem, 4vw, 2.8rem);
+    line-height: 1.05;
+    text-wrap: balance;
+    color: var(--text-light);
+  }
+  .b-contact__subtitle {
+    margin: 0.15rem 0 0;
+    font-family: var(--font-heading);
+    font-weight: 600;
+    color: var(--gold);
+  }
+  .b-contact__items {
+    list-style: none;
+    margin: 0; padding: 0;
+    display: flex; flex-direction: column; gap: 0.6rem;
+  }
+  .b-contact__item {
+    display: flex; align-items: center; gap: 0.75rem;
+    padding: 0.7rem 1rem;
+    border-radius: var(--radius-sm);
+    background: color-mix(in srgb, #000 22%, transparent);
+    border: 1px solid color-mix(in srgb, #fff 14%, transparent);
+    color: var(--text-light);
+    font-family: var(--font-heading);
+    font-weight: 600;
+    font-size: 0.95rem;
+    text-decoration: none;
+    transition: border-color 0.15s ease, background 0.15s ease;
+  }
+  a.b-contact__item:hover {
+    border-color: var(--gold);
+    background: color-mix(in srgb, #000 12%, transparent);
+  }
+  a.b-contact__item:focus-visible { outline: 2px solid var(--gold); outline-offset: 2px; }
+  .b-contact__icon { display: inline-flex; color: var(--gold); flex: 0 0 auto; }
+  .b-contact__value { min-width: 0; overflow-wrap: anywhere; }
+  .b-contact__note {
+    grid-column: 1 / -1;
+    margin: 0;
+    padding-top: 1.25rem;
+    border-top: 1px solid color-mix(in srgb, #fff 14%, transparent);
+    color: color-mix(in srgb, var(--text-light) 78%, transparent);
+    font-size: 0.9rem;
+    line-height: 1.6;
+  }
+</style>

package/components/recipes/Faq.astro

@@ -3,12 +3,16 @@
  *  question/answer items. Uses native <details>/<summary> — accessible and
  *  interactive with zero JavaScript. Composes the Heading primitive. */
 import Heading from '../blocks/Heading.astro';
+import { inlineMarkdown } from '../../lib/inline-markdown';
 
 interface Props {
   title?: string;
   items?: { question: string; answer: string }[];
 }
 const { title, items = [] } = Astro.props;
+// Answers may carry a link or bold via a tiny markdown subset (inlineMarkdown),
+// split into paragraphs on blank lines. Trusted editor/CMS text, sanitised.
+const paragraphs = (answer: string) => answer.split(/\n\s*\n/).map((p) => p.trim()).filter(Boolean);
 ---
 
 <section class="b-faq">
@@ -17,7 +21,9 @@ const { title, items = [] } = Astro.props;
     {items.map((item) => (
       <details class="b-faq__item">
         <summary class="b-faq__q">{item.question}</summary>
-        <div class="b-faq__a"><p>{item.answer}</p></div>
+        <div class="b-faq__a">
+          {paragraphs(item.answer).map((p) => <p set:html={inlineMarkdown(p)} />)}
+        </div>
       </details>
     ))}
   </div>

package/components/recipes/LatestPosts.astro

@@ -11,7 +11,7 @@ import PostCard from '../PostCard.astro';
 import Heading from '../blocks/Heading.astro';
 import Button from '../Button.astro';
 import { getIndexPosts, getPostsByTag } from '../../lib/posts';
-import { isRecent } from '../../content/posts';
+import { isRecent, postLink } from '../../content/posts';
 
 interface Props {
   title?: string;
@@ -68,12 +68,12 @@ const isNew = (date: Date | string) => isRecent(date, newWithinDays, nowMs);
     <ul class="b-latest-posts__list">
       {posts.map((p, i) => {
         const { iso, label } = fmt(p.data.date);
-        const href = `/posts/${p.slug}`;
+        const { href, newTab } = postLink(p);
         const cats = (p.data.tags ?? []).slice(0, 2);
         return (
           <li class="b-post-row">
             {p.data.heroImage && (
-              <a class="b-post-row__media" href={href} tabindex="-1" aria-hidden="true">
+              <a class="b-post-row__media" href={href} target={newTab ? '_blank' : undefined} rel={newTab ? 'noopener' : undefined} tabindex="-1" aria-hidden="true">
                 <img src={p.data.heroImage} alt="" loading="lazy" />
               </a>
             )}
@@ -81,7 +81,7 @@ const isNew = (date: Date | string) => isRecent(date, newWithinDays, nowMs);
               {cats.length > 0 && (
                 <span class="b-post-row__cat">{cats.join(' · ')}</span>
               )}
-              <h3 class="b-post-row__title"><a href={href}>{p.data.title}</a></h3>
+              <h3 class="b-post-row__title"><a href={href} target={newTab ? '_blank' : undefined} rel={newTab ? 'noopener' : undefined}>{p.data.title}</a></h3>
             </div>
             <div class="b-post-row__aside">
               {i === 0 && isNew(p.data.date) && <span class="b-post-row__new">New</span>}
@@ -94,16 +94,21 @@ const isNew = (date: Date | string) => isRecent(date, newWithinDays, nowMs);
     </ul>
   ) : (
     <div class="b-latest-posts__grid">
-      {posts.map((p) => (
-        <PostCard
-          href={`/posts/${p.slug}`}
-          title={p.data.title}
-          date={p.data.date}
-          summary={p.data.summary}
-          heroImage={p.data.heroImage}
-          tagLabels={p.data.tags}
-        />
-      ))}
+      {posts.map((p) => {
+        const { href, newTab } = postLink(p);
+        return (
+          <PostCard
+            href={href}
+            newTab={newTab}
+            moreLabel={newTab ? 'Open PDF' : undefined}
+            title={p.data.title}
+            date={p.data.date}
+            summary={p.data.summary}
+            heroImage={p.data.heroImage}
+            tagLabels={p.data.tags}
+          />
+        );
+      })}
     </div>
   )}
 

package/components/recipes/Locations.astro

@@ -0,0 +1,150 @@
+---
+/**
+ * Locations ("Where to find us") — a Level-2 recipe: one or more places, each a
+ * neat tile with a consent-gated map on top and its name / address / directions
+ * below. Replaces stacking bare map embeds. The map loads once the visitor accepts
+ * the site cookie banner (shared consent — no per-tile gate for anyone who
+ * accepted); the per-tile "Show map" button is a fallback that grants the same
+ * consent. Token-driven, equal-height tiles. https embed URLs only.
+ */
+import Icon from '../Icon.astro';
+import Heading from '../blocks/Heading.astro';
+import { isSafeEmbedUrl } from '../../content/calendar';
+
+interface Item {
+  name: string;
+  address?: string;
+  embedUrl: string;
+  directionsUrl?: string;
+}
+interface Props {
+  title?: string;
+  intro?: string;
+  columns?: 1 | 2;
+  provider?: string;
+  items?: Item[];
+}
+const { title, intro, columns = 2, provider = 'Google Maps', items = [] } = Astro.props;
+---
+
+<section class="b-locations">
+  {(title || intro) && (
+    <div class="b-locations__head">
+      {title && <Heading text={title} level={2} />}
+      {intro && <p class="b-locations__intro">{intro}</p>}
+    </div>
+  )}
+  <div class="b-locations__grid" data-cols={columns}>
+    {items.map((item) => (
+      <article class="b-locations__card">
+        <div class="b-locations__map">
+          {isSafeEmbedUrl(item.embedUrl) ? (
+            <div class="b-loc-map" data-embed-url={item.embedUrl} data-title={`Map — ${item.name}`}>
+              <div class="b-loc-map__consent">
+                <p class="b-loc-map__text">This map is provided by {provider}.</p>
+                <button type="button" class="b-loc-map__load">Show map</button>
+              </div>
+              <div class="b-loc-map__frame"></div>
+            </div>
+          ) : (
+            <div class="b-loc-map__fallback" aria-hidden="true"><Icon name="map-pin" size={30} /></div>
+          )}
+        </div>
+        <div class="b-locations__body">
+          <h3 class="b-locations__name">{item.name}</h3>
+          {item.address && <p class="b-locations__address">{item.address}</p>}
+          {item.directionsUrl && (
+            <a class="b-locations__dir" href={item.directionsUrl} target="_blank" rel="noopener">
+              Get directions <span aria-hidden="true">→</span>
+            </a>
+          )}
+        </div>
+      </article>
+    ))}
+  </div>
+</section>
+
+<script>
+  // Shared site consent: accepting the cookie banner auto-loads every map here.
+  import { hasConsent, setConsent, onConsentChange } from '../../lib/consent-client';
+
+  const maps = document.querySelectorAll<HTMLElement>('.b-loc-map');
+  function load(el: HTMLElement) {
+    if (el.dataset.loaded === 'true') return;
+    const url = el.dataset.embedUrl;
+    const slot = el.querySelector<HTMLElement>('.b-loc-map__frame');
+    if (!url || !slot) return;
+    const frame = document.createElement('iframe');
+    frame.src = url;
+    frame.title = el.dataset.title || 'Map';
+    frame.loading = 'lazy';
+    frame.referrerPolicy = 'no-referrer-when-downgrade';
+    frame.style.width = '100%';
+    frame.style.height = '100%';
+    frame.style.border = '0';
+    slot.replaceChildren(frame);
+    el.dataset.loaded = 'true';
+    const consent = el.querySelector<HTMLElement>('.b-loc-map__consent');
+    if (consent) consent.hidden = true;
+  }
+  const loadAll = () => maps.forEach(load);
+
+  if (hasConsent()) loadAll();
+  onConsentChange((allowed) => { if (allowed) loadAll(); });
+  maps.forEach((el) => {
+    el.querySelector<HTMLButtonElement>('.b-loc-map__load')?.addEventListener('click', () => setConsent(true));
+  });
+</script>
+
+<style>
+  .b-locations {
+    display: flex;
+    flex-direction: column;
+    gap: 1.75rem;
+    max-width: 72rem;
+    margin-inline: auto;
+    padding-inline: 1rem;
+  }
+  .b-locations__head { display: flex; flex-direction: column; gap: 0.6rem; }
+  .b-locations__intro { margin: 0; color: var(--muted); max-width: var(--max); }
+  .b-locations__grid { display: grid; grid-template-columns: 1fr; gap: 1.5rem; }
+  @media (min-width: 44em) {
+    .b-locations__grid[data-cols='2'] { grid-template-columns: repeat(2, 1fr); }
+  }
+  .b-locations__card {
+    display: flex;
+    flex-direction: column;
+    background: var(--bg-surface);
+    border: var(--card-border);
+    border-radius: var(--radius);
+    box-shadow: var(--shadow-sm);
+    overflow: hidden;
+  }
+  /* Map region — uniform ratio; the consent card fills it until the iframe loads. */
+  .b-locations__map { position: relative; aspect-ratio: 4 / 3; background: var(--bg-section); }
+  .b-loc-map, .b-loc-map__frame, .b-loc-map__consent, .b-loc-map__fallback { position: absolute; inset: 0; }
+  .b-loc-map__frame :global(iframe) { display: block; }
+  .b-loc-map__consent {
+    display: flex; flex-direction: column; align-items: center; justify-content: center;
+    gap: 0.75rem; padding: 1.5rem; text-align: center;
+  }
+  .b-loc-map__consent[hidden] { display: none; }
+  .b-loc-map__text { margin: 0; color: var(--muted); font-size: 0.9rem; max-width: 32ch; }
+  .b-loc-map__load {
+    font: inherit; font-family: var(--font-heading); font-weight: 600; font-size: 0.9rem;
+    padding: 0.5rem 1.1rem; border: none; border-radius: var(--radius-sm);
+    background: var(--gold); color: var(--text-light); cursor: pointer;
+    transition: filter 0.15s ease;
+  }
+  .b-loc-map__load:hover { filter: brightness(0.94); }
+  .b-loc-map__load:focus-visible { outline: 2px solid var(--gold); outline-offset: 2px; }
+  .b-loc-map__fallback { display: flex; align-items: center; justify-content: center; color: var(--muted); }
+  .b-locations__body { display: flex; flex-direction: column; gap: 0.4rem; padding: 1.1rem 1.2rem 1.3rem; }
+  .b-locations__name { margin: 0; font-size: 1.15rem; }
+  .b-locations__address { margin: 0; color: var(--muted); line-height: 1.55; white-space: pre-line; }
+  .b-locations__dir {
+    margin-top: 0.35rem;
+    font-family: var(--font-heading); font-weight: 600; font-size: 0.9rem;
+    color: var(--gold);
+  }
+</style>

package/components/recipes/MapEmbed.astro

@@ -71,43 +71,37 @@ const safe = isSafeEmbedUrl(embedUrl);
 </section>
 
 <script>
-  // Bundled (not is:inline), so it runs once even with multiple maps on a page.
-  // Wires each embed's consent gate; auto-loads where consent was given.
-  const CONSENT_KEY = 'ferst-map-consent';
-  document.querySelectorAll<HTMLElement>('.b-map__embed').forEach((el) => {
+  // Bundled (runs once even with multiple maps on a page). Uses the shared site
+  // embed consent: accepting the cookie banner (or the footer panel) auto-loads
+  // every embed. The per-embed button grants that same consent as a fallback.
+  import { hasConsent, setConsent, onConsentChange } from '../../lib/consent-client';
+
+  const embeds = document.querySelectorAll<HTMLElement>('.b-map__embed');
+
+  function load(el: HTMLElement) {
+    if (el.dataset.loaded === 'true') return;
     const url = el.dataset.embedUrl;
-    if (!url) return;
-    const height = el.dataset.height || '450';
-    const title = el.dataset.title || 'Map';
     const frameSlot = el.querySelector<HTMLElement>('.b-map__frame');
+    if (!url || !frameSlot) return;
+    const frame = document.createElement('iframe');
+    frame.src = url;
+    frame.title = el.dataset.title || 'Map';
+    frame.loading = 'lazy';
+    frame.referrerPolicy = 'no-referrer-when-downgrade';
+    frame.style.width = '100%';
+    frame.style.height = (el.dataset.height || '450') + 'px';
+    frame.style.border = '0';
+    frameSlot.replaceChildren(frame);
+    el.dataset.loaded = 'true';
     const consent = el.querySelector<HTMLElement>('.b-map__consent');
-    const btn = el.querySelector<HTMLButtonElement>('.b-map__load');
-
-    function load() {
-      if (el.dataset.loaded === 'true' || !frameSlot) return;
-      const frame = document.createElement('iframe');
-      frame.src = url as string;
-      frame.title = title;
-      frame.loading = 'lazy';
-      frame.referrerPolicy = 'no-referrer-when-downgrade';
-      frame.style.width = '100%';
-      frame.style.height = height + 'px';
-      frame.style.border = '0';
-      frameSlot.replaceChildren(frame);
-      el.dataset.loaded = 'true';
-      if (consent) consent.hidden = true;
-    }
-
-    try {
-      if (localStorage.getItem(CONSENT_KEY) === '1') load();
-    } catch (_) {}
+    if (consent) consent.hidden = true;
+  }
+  const loadAll = () => embeds.forEach(load);
 
-    btn?.addEventListener('click', () => {
-      try {
-        localStorage.setItem(CONSENT_KEY, '1');
-      } catch (_) {}
-      load();
-    });
+  if (hasConsent()) loadAll();
+  onConsentChange((allowed) => { if (allowed) loadAll(); });
+  embeds.forEach((el) => {
+    el.querySelector<HTMLButtonElement>('.b-map__load')?.addEventListener('click', () => setConsent(true));
   });
 </script>
 

package/content/blocks.ts

@@ -480,6 +480,47 @@ export const mediaCardsBlock = z.object({
     .default([]),
 });
 
+/** ContactCard — a branded "get in touch" band: display title + subtitle on the
+ *  left, contact channels as tappable pills on the right, a note across the bottom. */
+export const contactCardBlock = z.object({
+  type: z.literal('contactCard'),
+  enabled: z.boolean().default(true),
+  eyebrow: z.string().optional(),
+  title: z.string(),
+  subtitle: z.string().optional(),
+  note: z.string().optional(),
+  items: z
+    .array(
+      z.object({
+        icon: z.string().optional(),
+        value: z.string(),
+        href: z.string().optional(),
+      })
+    )
+    .default([]),
+});
+
+/** Locations ("Where to find us") — location tiles, each a consent-gated map over
+ *  a name / address / directions. https embed URLs only (isSafeEmbedUrl). */
+export const locationsBlock = z.object({
+  type: z.literal('locations'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  columns: z.union([z.literal(1), z.literal(2)]).default(2),
+  provider: z.string().default('Google Maps'),
+  items: z
+    .array(
+      z.object({
+        name: z.string(),
+        address: z.string().optional(),
+        embedUrl: z.string(),
+        directionsUrl: z.string().optional(),
+      })
+    )
+    .default([]),
+});
+
 export type RecipeBlock =
   | z.infer<typeof heroBlock>
   | z.infer<typeof featureCardsBlock>
@@ -503,7 +544,9 @@ export type RecipeBlock =
   | z.infer<typeof mapEmbedBlock>
   | z.infer<typeof tableBlock>
   | z.infer<typeof noticeBlock>
-  | z.infer<typeof mediaCardsBlock>;
+  | z.infer<typeof mediaCardsBlock>
+  | z.infer<typeof contactCardBlock>
+  | z.infer<typeof locationsBlock>;
 
 /* ── Level-1 layout / container primitives ─────────────────────────────────
  * These hold child blocks, so the schema is **recursive** (a container's
@@ -612,6 +655,8 @@ export const blockSchema = z.discriminatedUnion('type', [
   tableBlock,
   noticeBlock,
   mediaCardsBlock,
+  contactCardBlock,
+  locationsBlock,
   sectionBlock,
   gridBlock,
   stackBlock,
@@ -644,6 +689,23 @@ export const pageSchema = z.object({
    * bespoke page may have none.
    */
   templateId: z.string().optional(),
+  /**
+   * Editor change-requests captured in the CMS — the seed of AI-driven editing
+   * ([[ferst_editing_ai_first_pdlc]]): rather than let editors edit block JSON
+   * directly (easy to break), they describe a desired change against the page and
+   * it's stored here for an agent to action later → PR → human verify. NEVER
+   * rendered; carried through the schema so a CMS save preserves it.
+   */
+  requests: z
+    .array(
+      z.object({
+        text: z.string(),
+        at: z.string().optional(),
+        by: z.string().optional(),
+        status: z.enum(['open', 'done']).default('open'),
+      }),
+    )
+    .default([]),
   /** Keep the JSON in the repo but exclude it from the build. */
   draft: z.boolean().default(false),
   blocks: z.array(blockSchema).default([]),

package/content/posts.ts

@@ -88,6 +88,23 @@ export function tagCounts(posts: Array<{ data: { tags?: string[] } }>): Record<s
   return counts;
 }
 
+/**
+ * Where a post card/row should link. Normally the post's own page — but a post
+ * that is just an attached file with no body (e.g. a newsletter that's only a PDF)
+ * links straight to the file, opened in a new tab, so there's no empty post page
+ * in between. Pure; the caller passes the entry's `body` (raw markdown) so
+ * "has text" is decided here.
+ */
+export function postLink(
+  post: { slug: string; body?: string | null; data: { attachment?: string } },
+  base = '/posts',
+): { href: string; newTab: boolean } {
+  const attachment = post.data.attachment;
+  const hasBody = !!post.body && post.body.trim() !== '';
+  if (attachment && !hasBody) return { href: attachment, newTab: true };
+  return { href: `${base}/${post.slug}`, newTab: false };
+}
+
 /**
  * Whether a post date is within the last `days` of `now` — used to flag a "New"
  * badge in the compact latest-posts list. `days <= 0` disables it; a future or

package/content/schemas.ts

@@ -126,6 +126,22 @@ export const themeSettingsSchema = z.object({
   stroke: z.enum(['on', 'off']).default('on'),
   /** Input treatment — a single site-wide choice (a `data-field` attr on <html>). */
   fields: z.enum(['boxed', 'filled', 'underline']).default('boxed'),
+  /** Dark-mode formula knobs (root-derivation model). `darkDepth` = how light the
+   *  dark page background sits (OKLCH L); `darkChroma` = the cap on how much colour
+   *  the dark ground may carry. Both feed the AUTOMATIC dark roots. */
+  darkDepth: z.number().min(0.12).max(0.4).default(0.21),
+  darkChroma: z.number().min(0).max(0.15).default(0.05),
+  /** Explicit overrides for the three dark ROOTS. Each blank ⇒ the root is derived
+   *  from its light source by the formula; set ⇒ every dark token in that role
+   *  re-derives from this colour. Roots only (ground / text / accent) — never a
+   *  lone downstream token — so the palette can never fall out of sync. */
+  darkOverrides: z
+    .object({
+      ground: z.string().default(''),
+      text: z.string().default(''),
+      accent: z.string().default(''),
+    })
+    .default({}),
   /** Raw per-token overrides, layered last. Rarely needed. */
   advanced: z
     .object({

package/layouts/Base.astro

@@ -24,6 +24,7 @@ import '../styles/fonts.css';
 import SiteHeader from '../components/SiteHeader.astro';
 import SiteFooter from '../components/SiteFooter.astro';
 import CookiePreferences from '../components/CookiePreferences.astro';
+import CookieBanner from '../components/CookieBanner.astro';
 import StickyCallout from '../components/StickyCallout.astro';
 import SecondaryLogo from '../components/SecondaryLogo.astro';
 import { loadSiteSettings } from '../lib/siteSettings';
@@ -170,6 +171,7 @@ const metaDescription = description ?? identity.description;
     />
 
     <CookiePreferences />
+    <CookieBanner />
 
     <StickyCallout {...callout} />
 

package/lib/consent-client.ts

@@ -0,0 +1,46 @@
+/**
+ * Client-only consent state for embedded third-party content (Google Calendar,
+ * Google Maps). One shared key + event so the cookie banner, the footer's cookie
+ * preferences panel, and every embed on the page stay in sync: accept once (via
+ * the banner) and every embed loads — no separate per-embed gate.
+ *
+ * Import this ONLY from component `<script>` blocks (it touches localStorage /
+ * document). Every accessor is wrapped so a blocked/absent storage never throws.
+ */
+export const CONSENT_KEY = 'ferst-embed-consent';
+export const CONSENT_EVENT = 'ferst-embed-consent-changed';
+
+/** True once the visitor has explicitly accepted embedded content. */
+export function hasConsent(): boolean {
+  try {
+    return localStorage.getItem(CONSENT_KEY) === '1';
+  } catch {
+    return false;
+  }
+}
+
+/** True once the visitor has made ANY choice (accept or decline) — hides the banner. */
+export function isDecided(): boolean {
+  try {
+    return localStorage.getItem(CONSENT_KEY) !== null;
+  } catch {
+    return false;
+  }
+}
+
+/** Record a choice and broadcast it so open embeds react immediately. */
+export function setConsent(granted: boolean): void {
+  try {
+    localStorage.setItem(CONSENT_KEY, granted ? '1' : '0');
+  } catch {
+    /* storage blocked — the event below still drives this page */
+  }
+  document.dispatchEvent(new CustomEvent(CONSENT_EVENT, { detail: { allowed: granted } }));
+}
+
+/** Subscribe to consent changes (fires with the new allowed state). */
+export function onConsentChange(cb: (allowed: boolean) => void): void {
+  document.addEventListener(CONSENT_EVENT, (e) => {
+    cb((e as CustomEvent).detail?.allowed === true);
+  });
+}

package/lib/inline-markdown.ts

@@ -0,0 +1,52 @@
+/**
+ * inlineMarkdown — render a *tiny*, safe subset of markdown from trusted editor/CMS
+ * text: links `[label](href)`, bold `**text**`, and single newlines → `<br>`.
+ * Everything is HTML-escaped first, and only safe href schemes (http(s), root-
+ * relative, mailto, tel, in-page #anchors) become links — an unsafe href renders
+ * as literal text. The result is safe to drop into `set:html` for trusted content.
+ *
+ * This exists so recipes that show a line or two of editor copy (FAQ answers,
+ * notices) can carry a link without a full markdown pipeline — and without the
+ * `[text](url)` showing through as literal characters.
+ */
+const ESCAPE: Record<string, string> = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+};
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) => ESCAPE[c]);
+}
+
+/** Only these href schemes are allowed to become real links. */
+const SAFE_HREF = /^(?:https?:\/\/|\/|mailto:|tel:|#)/i;
+
+const LINK_RE = /\[([^\]]+)\]\(([^)\s]+)\)/g;
+
+/** Bold + single-newline breaks, applied to already-escaped text. */
+function inlineFormat(escaped: string): string {
+  return escaped.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>').replace(/\n/g, '<br>');
+}
+
+export function inlineMarkdown(text: string | undefined | null): string {
+  if (!text) return '';
+  let out = '';
+  let last = 0;
+  let m: RegExpExecArray | null;
+  LINK_RE.lastIndex = 0;
+  while ((m = LINK_RE.exec(text))) {
+    out += inlineFormat(escapeHtml(text.slice(last, m.index)));
+    const label = inlineFormat(escapeHtml(m[1]));
+    const href = m[2];
+    if (SAFE_HREF.test(href)) {
+      out += `<a href="${escapeHtml(href)}">${label}</a>`;
+    } else {
+      out += inlineFormat(escapeHtml(m[0])); // unsafe scheme → keep literal
+    }
+    last = m.index + m[0].length;
+  }
+  out += inlineFormat(escapeHtml(text.slice(last)));
+  return out;
+}

package/lib/posts.ts

@@ -24,6 +24,10 @@ import {
   type PostsSettings,
 } from '../content/posts';
 
+// Re-export the pure link helper so clients can import it alongside the data
+// helpers (e.g. a custom NewsList) from one place.
+export { postLink } from '../content/posts';
+
 export type PostEntry = CollectionEntry<'posts'>;
 
 /** A tag resolved for display: its slug + label/description + how many posts use it. */

package/lib/themeTokens.ts

@@ -66,29 +66,84 @@ const LIGHT_DERIVATION = [
   '--news-card-meta:color-mix(in srgb, var(--ink) 72%, var(--surface))',
 ].join(';');
 
-/** Dark-mode derivations — the OKLCH translation of the same three source vars. */
-const DARK_DERIVATION = [
-  '--fg:oklch(from var(--ink) 0.94 calc(c * 0.3) h)',
-  '--muted:oklch(from var(--ink) 0.74 calc(c * 0.3) h)',
-  '--accent:oklch(from var(--ink) 0.86 calc(c * 0.3) h)',
-  '--brown:oklch(from var(--ink) 0.74 calc(c * 0.3) h)',
-  '--bg:oklch(from var(--brand) 0.16 0.015 h)',
-  '--bg-surface:oklch(from var(--brand) 0.21 0.02 h)',
-  '--bg-section:oklch(from var(--brand) 0.19 0.018 h)',
-  '--bg-tag:oklch(from var(--brand) 0.14 0.015 h)',
-  '--dark-bg:oklch(from var(--brand) 0.12 0.015 h)',
-  '--border:oklch(from var(--brand) 0.32 0.02 h)',
-  '--gold:oklch(from var(--brand) 0.78 calc(c * 0.9) h)',
-  '--gold-light:oklch(from var(--brand) 0.30 calc(c * 0.55) h)',
-  '--accent-2:oklch(from var(--brand) 0.70 calc(c * 0.9) calc(h + 26))',
-  '--text-footer:oklch(from var(--ink) 0.74 calc(c * 0.3) h)',
-  '--text-footer-link:oklch(from var(--brand) 0.78 calc(c * 0.9) h)',
-  '--text-copyright:oklch(from var(--ink) 0.55 calc(c * 0.3) h)',
-  '--text-subtle:oklch(from var(--ink) 0.55 calc(c * 0.3) h)',
-  '--divider-dark:oklch(from var(--brand) 0.32 0.02 h)',
-  '--news-card-meta:oklch(from var(--ink) 0.74 calc(c * 0.3) h)',
+/**
+ * Dark mode uses a ROOT-DERIVATION model that mirrors light's three sources, so an
+ * editor can only ever change coherent roots — never a lone downstream token that
+ * would then clash with the rest.
+ *
+ * Three dark ROOTS, one per role:
+ *   --dark-ground  (surfaces)  ← surface, chroma BOOSTED as it darkens so a pale
+ *                                tint survives instead of collapsing to grey/black;
+ *                                lightness = --dark-bg-l (the depth knob).
+ *   --dark-text    (text)      ← ink, lightened for a dark ground.
+ *   --dark-accent  (accents)   ← brand, brightened for a dark ground.
+ * Each defaults to this formula but can be OVERRIDDEN with an explicit colour (see
+ * buildThemeStyle); either way EVERY dark token below derives from the three roots,
+ * so the palette stays internally consistent whether automatic or hand-set.
+ */
+const DARK_ROOTS_AUTO = [
+  '--dark-ground:oklch(from var(--surface) var(--dark-bg-l) clamp(0, calc(c * 3.5), var(--dark-chroma-cap)) h)',
+  '--dark-text:oklch(from var(--ink) 0.94 calc(c * 0.3) h)',
+  '--dark-accent:oklch(from var(--brand) 0.78 calc(c * 0.9) h)',
 ].join(';');
 
+/** Every working dark token, derived from the three roots (offsets in OKLCH L). */
+const DARK_DOWNSTREAM = [
+  // Grounds ← --dark-ground
+  '--bg:var(--dark-ground)',
+  '--bg-surface:oklch(from var(--dark-ground) calc(l + 0.05) c h)',
+  '--bg-section:oklch(from var(--dark-ground) calc(l + 0.025) c h)',
+  '--bg-tag:oklch(from var(--dark-ground) calc(l - 0.03) c h)',
+  '--dark-bg:oklch(from var(--dark-ground) calc(l - 0.05) c h)',
+  '--border:oklch(from var(--dark-ground) calc(l + 0.19) c h)',
+  '--divider-dark:oklch(from var(--dark-ground) calc(l + 0.19) c h)',
+  // Text ← --dark-text
+  '--fg:var(--dark-text)',
+  '--muted:oklch(from var(--dark-text) calc(l - 0.20) c h)',
+  '--accent:oklch(from var(--dark-text) calc(l - 0.08) c h)',
+  '--brown:oklch(from var(--dark-text) calc(l - 0.20) c h)',
+  '--text-footer:oklch(from var(--dark-text) calc(l - 0.20) c h)',
+  '--text-copyright:oklch(from var(--dark-text) calc(l - 0.39) c h)',
+  '--text-subtle:oklch(from var(--dark-text) calc(l - 0.39) c h)',
+  '--news-card-meta:oklch(from var(--dark-text) calc(l - 0.20) c h)',
+  // Accents ← --dark-accent
+  '--gold:var(--dark-accent)',
+  '--gold-light:oklch(from var(--dark-accent) calc(l - 0.46) calc(c * 0.6) h)',
+  '--accent-2:oklch(from var(--dark-accent) calc(l - 0.08) c calc(h + 26))',
+  '--text-footer-link:var(--dark-accent)',
+].join(';');
+
+/** Defaults for the dark-formula knobs (also the CMS/schema defaults). */
+export const DARK_DEFAULTS = { depth: 0.21, chroma: 0.05 } as const;
+
+/** Clamp a numeric knob to a range, falling back to `fallback` when absent/NaN. */
+function clampNum(v: unknown, min: number, max: number, fallback: number): number {
+  const n = typeof v === 'number' && Number.isFinite(v) ? v : fallback;
+  return Math.min(max, Math.max(min, n));
+}
+
+/**
+ * Compose the dark block: the depth/chroma knobs, the three auto roots, any
+ * explicit root overrides (which win over the auto value), then the downstream
+ * derivations that read whichever root value ended up winning.
+ */
+function darkDeclarations(theme: ThemeSettings): string {
+  const depth = clampNum(theme.darkDepth, 0.12, 0.4, DARK_DEFAULTS.depth);
+  const chroma = clampNum(theme.darkChroma, 0, 0.15, DARK_DEFAULTS.chroma);
+  const ov = theme.darkOverrides ?? {};
+  const overrides: string[] = [];
+  if (clean(ov.ground)) overrides.push(`--dark-ground:${clean(ov.ground)}`);
+  if (clean(ov.text)) overrides.push(`--dark-text:${clean(ov.text)}`);
+  if (clean(ov.accent)) overrides.push(`--dark-accent:${clean(ov.accent)}`);
+  return [
+    `--dark-bg-l:${depth}`,
+    `--dark-chroma-cap:${chroma}`,
+    DARK_ROOTS_AUTO,
+    ...overrides,
+    DARK_DOWNSTREAM,
+  ].join(';');
+}
+
 /** Drop a value that could break out of a CSS declaration. The source is trusted
  *  repo JSON, but this keeps a stray value honest (defence in depth). */
 function clean(v: unknown): string {
@@ -151,7 +206,7 @@ export function buildThemeStyle(theme: ThemeSettings): ThemeStyle {
   const css = [
     rootDecls.length ? `:root:root{${rootDecls.join(';')}}` : '',
     themed ? `:root:root:not([data-theme="dark"]){${LIGHT_DERIVATION}}` : '',
-    themed ? `:root:root[data-theme="dark"]{${DARK_DERIVATION}}` : '',
+    themed ? `:root:root[data-theme="dark"]{${darkDeclarations(theme)}}` : '',
     rawBlock(':root:root', theme.advanced?.light),
     rawBlock(':root:root[data-theme="dark"]', theme.advanced?.dark),
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.2.9",
+  "version": "0.4.0",
   "type": "module",
   "description": "Ferst Core — the shared, brand-agnostic client-site system: Astro components, layouts, content schemas, the layered config resolver, and a neutral styling architecture that every client overrides.",
   "license": "BUSL-1.1",