ferst-core 0.1.0 → 0.2.1

package/content/posts.ts

@@ -0,0 +1,89 @@
+// The posts/blog capability contract — white-room, rebuilt on the block-system-era
+// core (no CTK code). A capability owns its own content schema (this file), its
+// collections (collections.ts), its rendering (components/Post*.astro) and its
+// data helpers (lib/posts.ts); a client repo carries only the post/tag DATA + a
+// couple of thin routes. Posts are ubiquitous/replicable → public (Tier 1a).
+//
+// Posts are authored as MARKDOWN (the editor-friendly long-form format, a Sveltia
+// markdown pane) + frontmatter metadata; the page a post renders into is composed
+// from the core chrome + a post layout. Tags are a small DATA collection so a tag
+// carries a label + description (canonical), and posts reference tags by slug.
+import { z } from 'zod';
+
+/** A tag — canonical metadata so tag pages can show a real label + description,
+ *  and posts reference tags by slug (the tag file's id). */
+export const tagSchema = z.object({
+  label: z.string(),
+  description: z.string().default(''),
+  /** Keep the tag defined but hide it from tag listings. */
+  hidden: z.boolean().default(false),
+});
+
+/** A blog/news post: a markdown body (the collection content) + this frontmatter. */
+export const postSchema = z.object({
+  title: z.string(),
+  /** Publish date — drives ordering and the visible date. */
+  date: z.coerce.date(),
+  /** Short summary for cards / SEO. Falls back to a body excerpt when absent. */
+  summary: z.string().optional(),
+  /** Tag slugs (each matches a `tags/<slug>` entry). */
+  tags: z.array(z.string()).default([]),
+  /** Optional hero / preview image. */
+  heroImage: z.string().optional(),
+  /** Optional downloadable file attached to the post (e.g. a PDF newsletter or
+   *  notice). Rendered as a download link on the post. */
+  attachment: z.string().optional(),
+  /** Keep the post in the repo but exclude it from the build. */
+  draft: z.boolean().default(false),
+});
+
+/** Blog-wide settings — one focused CMS pane. */
+export const postsSettingsSchema = z.object({
+  /** Heading for the main news index. */
+  title: z.string().default('News'),
+  /** Optional intro copy for the index. */
+  intro: z.string().default(''),
+  /** Posts per page in the paginated index. */
+  perPage: z.number().int().min(1).default(9),
+  /** Tag slugs excluded from the MAIN index (e.g. a `newsletter` tag that has its
+   *  own view). Kept generic — no capability knows what "newsletter" means. */
+  excludeFromIndex: z.array(z.string()).default([]),
+});
+
+export type Tag = z.infer<typeof tagSchema>;
+export type Post = z.infer<typeof postSchema>;
+export type PostsSettings = z.infer<typeof postsSettingsSchema>;
+
+// ── Pure selection helpers ────────────────────────────────────────────────────
+// Kept here (no `astro:content` import) so they're unit-testable as plain
+// functions; lib/posts.ts wraps `getCollection` around them. Generic over the
+// minimal shape they read, so they work on real collection entries.
+
+/** Newest first, by `data.date`. Does not mutate the input. */
+export function sortByDateDesc<T extends { data: { date: Date } }>(posts: T[]): T[] {
+  return [...posts].sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());
+}
+
+/** Drop posts flagged `draft`. */
+export function dropDrafts<T extends { data: { draft?: boolean } }>(posts: T[]): T[] {
+  return posts.filter((p) => !p.data.draft);
+}
+
+/** Drop posts carrying ANY of the excluded tag slugs. */
+export function excludeTags<T extends { data: { tags?: string[] } }>(posts: T[], exclude: string[]): T[] {
+  if (exclude.length === 0) return posts;
+  const set = new Set(exclude);
+  return posts.filter((p) => !(p.data.tags ?? []).some((t) => set.has(t)));
+}
+
+/** Keep only posts carrying the given tag slug. */
+export function withTag<T extends { data: { tags?: string[] } }>(posts: T[], tag: string): T[] {
+  return posts.filter((p) => (p.data.tags ?? []).includes(tag));
+}
+
+/** Count how many posts carry each tag slug. */
+export function tagCounts(posts: Array<{ data: { tags?: string[] } }>): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const p of posts) for (const t of p.data.tags ?? []) counts[t] = (counts[t] ?? 0) + 1;
+  return counts;
+}

package/content/schemas.ts

@@ -1,52 +1,10 @@
-// Pure Zod schemas, separated from config.ts so they can be unit-tested
-// without pulling in `astro:content` (a virtual module that only exists
-// during Astro's build). config.ts wraps these with defineCollection.
+// Pure Zod schemas for the site-settings collections the chrome reads (identity +
+// contact, logos, navigation, footer, theme tokens). Separated from config.ts so
+// they can be unit-tested without `astro:content`. The page CONTENT model is the
+// block palette in `content/blocks.ts` — a page is an ordered list of typed
+// blocks, not a bespoke per-page-type schema.
 import { z } from 'zod';
 
-/** One “Get Involved” card on the home page (`GroupCard`). */
-export const homepageGroupSchema = z.object({
-  title: z.string(),
-  description: z.string(),
-  icon: z.enum(['prayer', 'charity', 'ordinariate', 'youth']).optional(),
-  /** Shown when `linkHref` is not set — mailto handled in `GroupCard`. */
-  contact: z.string().optional(),
-  contactLabel: z.string().optional(),
-  linkHref: z.string().optional(),
-  imageSrc: z.string().optional(),
-  imageAlt: z.string().optional(),
-});
-
-export const homepageSchema = z.object({
-  heroImage: z.string().optional(),
-  groups: z.array(homepageGroupSchema).default([]),
-});
-
-/**
- * Editor-managed tag vocabulary. A post's `tags` array stores these entries'
- * `name` values directly (not a slug/reference) — see the CMS `relation`
- * field config in scripts/build-admin-config.mjs — so this collection exists
- * purely to give editors a searchable, growable, typo-resistant picker
- * instead of a hardcoded list. The site itself never reads this collection;
- * only the CMS authoring UI does.
- */
-export const tagSchema = z.object({
-  name: z.string(),
-});
-
-/* ────────────────────────────────────────────────────────────────────────
- *  Site settings — split into several small single-purpose collections
- *  (logo / posts / calendar / navigation / identity+contact) instead of one
- *  big file, so each one is also its own focused Sveltia CMS pane rather
- *  than everything mushed onto a single long form. `src/lib/siteSettings.ts`
- *  merges all of these back into one `SiteSettings`-shaped object at read
- *  time, so every consumer keeps reading a single combined shape — only the
- *  underlying storage and CMS authoring surface are split.
- *
- *  Every nested object is `.default({})` so the data file only has to
- *  supply the keys it wants to override; defaults fill in the rest at
- *  parse time. That keeps schemas additive and JSON edits small.
- * ──────────────────────────────────────────────────────────────────── */
-
 const navLinkSchema = z.object({
   label: z.string(),
   href: z.string(),
@@ -67,31 +25,16 @@ const navGroupSchema = z.object({
   items: z.array(navGroupItemSchema).default([]),
 });
 
-const churchSchema = z.object({
-  name: z.string(),
-  /** One physical-address line per array entry; rendered with <br /> between. */
-  addressLines: z.array(z.string()).default([]),
-  /** Free-form Google Maps query; the page wraps it in maps.google.com/?q=. */
-  mapsQuery: z.string().optional(),
-});
-
 const siteIdentitySchema = z
   .object({
-    /** Used in <title> as " — {siteTitle}" and in the document description fallback.
-     *  Generic default — every client overrides via their siteSettings content. */
+    /** Used in <title> as " — {siteTitle}" and the description fallback. */
     siteTitle: z.string().default('Your Site'),
-    /** Short brand label — used in alt text. */
+    /** Short brand label — used in alt text and the footer. */
     shortName: z.string().default('Your Site'),
     /** Default <meta name="description"> when a page doesn't supply its own. */
     description: z.string().default('A website built with Ferst.'),
-    /** Optional org/parent line (e.g. a diocese, a group) — blank by default. */
-    diocese: z.string().default(''),
-    /** Town / city — appears under the hero title and elsewhere. */
+    /** Town / city — appended to the brand in alt text. */
     location: z.string().default(''),
-    /** Home-page hero copy. */
-    heroDiocese: z.string().default(''),
-    heroTitle: z.string().default('Welcome'),
-    heroLocation: z.string().default(''),
   })
   .default({});
 
@@ -99,27 +42,24 @@ const siteContactSchema = z
   .object({
     /** Human-readable phone number. Blank by default — client provides. */
     phoneDisplay: z.string().default(''),
-    /** Digits-only form used in `tel:` href. */
+    /** Digits-only form used in a `tel:` href. */
     phoneTel: z.string().default(''),
     email: z.string().default(''),
     facebookUrl: z.string().default(''),
-    /** One entry per physical location/site. Iterated on /contact/. */
-    churches: z.array(churchSchema).default([]),
   })
   .default({});
 
-/** Site identity + contact details. Everything else that used to live
- * alongside these (logos, posts-per-page, calendar ID, navigation) now has
- * its own collection — see below. */
+/** Site identity + contact details. Logos, navigation, footer and theme tokens
+ *  each have their own collection (below) so each is a focused CMS pane. */
 export const siteSettingsSchema = z.object({
   identity: siteIdentitySchema,
   contact: siteContactSchema,
 });
 
 export const logoSettingsSchema = z.object({
-  /** Primary/header logo — light theme variant. Optional — Base.astro falls back to a baked-in path. */
+  /** Primary/header logo — light theme variant. Optional (SiteHeader falls back to a wordmark). */
   primaryLogoLight: z.string().optional(),
-  /** Primary/header logo — dark theme variant. Optional — Base.astro falls back to a baked-in path. */
+  /** Primary/header logo — dark theme variant. Optional. */
   primaryLogoDark: z.string().optional(),
   /** Secondary/footer logo — light theme variant (optional). */
   secondaryLogoLight: z.string().optional(),
@@ -134,21 +74,10 @@ export const logoSettingsSchema = z.object({
     .default({}),
 });
 
-export const postsSettingsSchema = z.object({
-  postsPerPage: z.number().int().min(1).max(20).default(5),
-});
-
-export const calendarSettingsSchema = z.object({
-  /** Google Calendar ID (e.g. "abc123@group.calendar.google.com") embedded on /calendar/.
-   *  Blank by default — client provides; the calendar page can hide itself when unset. */
-  calendarId: z.string().default(''),
-});
-
 export const navbarSettingsSchema = z.object({
   /** Simple top-level links. Empty by default — every client defines its own nav. */
   primary: z.array(navLinkSchema).default([]),
-  /** Optional dropdown / mega-menu group (e.g. an "About" or "Services" menu).
-   *  Rendered by SiteHeader only when present — the core ships none. */
+  /** Optional dropdown / mega-menu group. Rendered by SiteHeader only when present. */
   dropdown: navGroupSchema.optional(),
 });
 
@@ -158,53 +87,59 @@ export const footerSettingsSchema = z.object({
 });
 
 /**
- * Client-overridable design tokens. Each key maps to a CSS custom property
- * (a leading `--` is added if omitted); the values are emitted into a
- * `<style>` in the document head that overrides the core's NEUTRAL defaults
- * in `styles/theme.css`. The core ships none — every client brings its own
- * palette here, so brand colours live in the client's repo (or, later, the
- * CMS), never baked into the shared core. `light` applies at `:root`, `dark`
- * under `[data-theme="dark"]`; only the keys a client sets are overridden,
- * the rest fall through to the neutral defaults.
+ * The brand — a client's design tokens, set in the CMS. The whole system is
+ * built to derive from just THREE source colours: `brand` (interactive accent),
+ * `ink` (text) and `surface` (background). `lib/themeTokens.ts` expands those
+ * into ~40 working tokens (light via `color-mix`, dark via an OKLCH translation
+ * — lightness flipped, hue kept, chroma damped so nothing turns neon), and
+ * `Base.astro` emits the result as a `<style>` that layers over the core's
+ * NEUTRAL defaults in `styles/theme.css`. Fonts and the four surface "knobs"
+ * (corners / elevation / stroke / fields) are the rest of the site-wide look —
+ * each set once, applied everywhere. `advanced.light/.dark` are a raw
+ * per-token escape hatch (power users / AI composition / back-compat) layered
+ * LAST. The core ships none of this — a brand lives in the client's repo (or
+ * the CMS), never baked into the shared core.
+ *
+ * This shape is what the Sveltia token pane edits (apps/showcase/public/admin):
+ * a client picks three colours + a font pairing + four knobs, not 40 tokens.
  */
 export const themeSettingsSchema = z.object({
-  light: z.record(z.string()).default({}),
-  dark: z.record(z.string()).default({}),
-});
-
-export const postSchema = z.object({
-  title: z.string(),
-  /** Author byline — shown in the CMS posts list and publicly under the post title.
-   * Expected on every post except newsletters, but Sveltia CMS can't enforce that
-   * conditionally, so it's optional here too (communicated via the CMS field hint). */
-  author: z.string().optional(),
-  date: z.coerce.date(),
-  /** A `newsletter`-tagged post is treated as a newsletter throughout the site
-   * (tag-driven, not a separate content type) — see src/content/filters.ts. */
-  tags: z.array(z.string()).default([]),
-  image: z.string().optional(),
-  /** Optional file (PDF, image, document). Expected for newsletter-tagged
-   * posts, which are otherwise body-less — communicated via the CMS hint,
-   * same conditional-required pattern as `author`. */
-  attachment: z.string().optional(),
-  // Visibility states. 'scheduled' is hidden from the site exactly like
-  // 'draft'; a separate cron worker flips due 'scheduled' posts to
-  // 'published' (commit → rebuild) once their `date` has passed.
-  status: z.enum(['published', 'draft', 'scheduled', 'archived']).default('published'),
+  /** Interactive accent — buttons, links, icons, highlights. Blank ⇒ neutral. */
+  brand: z.string().default(''),
+  /** Text colour — headings & body. Blank ⇒ neutral. */
+  ink: z.string().default(''),
+  /** Background — page, cards, sections (tints derived from it). Blank ⇒ neutral. */
+  surface: z.string().default(''),
+  /** Site-wide font pairing (role → CSS font-family stack). Blank ⇒ core default. */
+  fonts: z
+    .object({
+      heading: z.string().default(''),
+      body: z.string().default(''),
+      display: z.string().default(''),
+    })
+    .default({}),
+  /** Corner radius applied to every card / tile / input / button. */
+  corners: z.enum(['sharp', 'rounded', 'soft']).default('rounded'),
+  /** Card/tile elevation — `flat` removes the soft shadow site-wide. */
+  elevation: z.enum(['raised', 'flat']).default('raised'),
+  /** Card/tile stroke — `off` removes the 1px border site-wide. */
+  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'),
+  /** Raw per-token overrides, layered last. Rarely needed. */
+  advanced: z
+    .object({
+      light: z.record(z.string()).default({}),
+      dark: z.record(z.string()).default({}),
+    })
+    .default({}),
 });
 
-export type Post = z.infer<typeof postSchema>;
-export type Tag = z.infer<typeof tagSchema>;
-export type Homepage = z.infer<typeof homepageSchema>;
-export type HomepageGroup = z.infer<typeof homepageGroupSchema>;
 export type SiteSettings = z.infer<typeof siteSettingsSchema>;
 export type LogoSettings = z.infer<typeof logoSettingsSchema>;
-export type PostsSettings = z.infer<typeof postsSettingsSchema>;
-export type CalendarSettings = z.infer<typeof calendarSettingsSchema>;
 export type NavbarSettings = z.infer<typeof navbarSettingsSchema>;
 export type FooterSettings = z.infer<typeof footerSettingsSchema>;
 export type ThemeSettings = z.infer<typeof themeSettingsSchema>;
 export type NavLink = z.infer<typeof navLinkSchema>;
 export type NavGroup = z.infer<typeof navGroupSchema>;
 export type NavGroupItem = z.infer<typeof navGroupItemSchema>;
-export type Church = z.infer<typeof churchSchema>;

package/layouts/Base.astro

@@ -26,6 +26,7 @@ import SiteFooter from '../components/SiteFooter.astro';
 import CookiePreferences from '../components/CookiePreferences.astro';
 import SecondaryLogo from '../components/SecondaryLogo.astro';
 import { loadSiteSettings } from '../lib/siteSettings';
+import { buildThemeStyle } from '../lib/themeTokens';
 
 interface Props {
   title: string;
@@ -53,32 +54,20 @@ const { identity, contact, navigation, theme } = settings;
 
 const path = Astro.url.pathname;
 
-// Client design-token overrides → an inline <style> that layers over the
-// core's neutral defaults (styles/theme.css). Selectors are doubled
-// (`:root:root`, `:root[data-theme="dark"]`) so they win by specificity
-// regardless of stylesheet order. Keys are sanitised to `--custom-prop`
-// form and values that could break out of the declaration are dropped —
-// the source is trusted repo JSON, but this keeps a stray value honest.
-function tokenBlock(selector: string, tokens: Record<string, string>): string {
-  const decls = Object.entries(tokens ?? {})
-    .filter(([k, v]) => /^--?[a-zA-Z0-9-]+$/.test(k) && !/[<>{};]/.test(String(v)))
-    .map(([k, v]) => `${k.startsWith('--') ? k : `--${k}`}:${String(v).trim()}`)
-    .join(';');
-  return decls ? `${selector}{${decls}}` : '';
-}
-const themeCss = [
-  tokenBlock(':root:root', theme.light),
-  tokenBlock(':root[data-theme="dark"]', theme.dark),
-]
-  .filter(Boolean)
-  .join('');
+// The brand → an inline <style> that layers over the core's neutral defaults
+// (styles/theme.css). `buildThemeStyle` derives ~40 working tokens from the
+// three source colours (light color-mix + dark OKLCH) and emits the font/knob
+// overrides too; selectors are doubled (`:root:root`) so they win by
+// specificity regardless of stylesheet order. `themeField` is the site-wide
+// input treatment, applied as a `data-field` attribute on <html>.
+const { css: themeCss, field: themeField } = buildThemeStyle(theme);
 
-// Logos: schema marks them optional so legacy data files keep validating.
-// Fall back to paths that exist under `public/uploads/` in this repo (there is
-// no `uploads/branding/` tree — using it here caused broken images whenever
-// JSON omitted the keys or site settings fell back to schema defaults).
-const primaryLogoLight = settings.primaryLogoLight ?? '/uploads/logo-light.png';
-const primaryLogoDark = settings.primaryLogoDark ?? '/uploads/logo-dark.png';
+// Logos are optional. When a client hasn't configured one, SiteHeader renders a
+// text wordmark (the site name) rather than pointing <img> at a baked-in path
+// that may not exist — a broken logo by default was the old bug. Dark falls back
+// to the light variant when only one is supplied.
+const primaryLogoLight = settings.primaryLogoLight;
+const primaryLogoDark = settings.primaryLogoDark ?? settings.primaryLogoLight;
 const secondaryLogoLight = settings.secondaryLogoLight;
 const secondaryLogoDark = settings.secondaryLogoDark;
 const secondaryLogoLink = settings.secondaryLogoLink;
@@ -87,7 +76,7 @@ const metaDescription = description ?? identity.description;
 ---
 
 <!doctype html>
-<html lang="en-GB">
+<html lang="en-GB" data-field={themeField}>
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -117,11 +106,13 @@ const metaDescription = description ?? identity.description;
         }
         document.documentElement.dataset.theme = t;
         var logoHref = t === 'dark' ? primaryLogoDark : primaryLogoLight;
-        var link = document.createElement('link');
-        link.rel = 'preload';
-        link.as = 'image';
-        link.href = logoHref;
-        document.head.appendChild(link);
+        if (logoHref) {
+          var link = document.createElement('link');
+          link.rel = 'preload';
+          link.as = 'image';
+          link.href = logoHref;
+          document.head.appendChild(link);
+        }
       })();
     </script>
     <script>
@@ -189,7 +180,7 @@ const metaDescription = description ?? identity.description;
         overscroll-behavior-x: none;
       }
       body {
-        font-family: 'Inter', 'Lato', Georgia, serif;
+        font-family: var(--font-body);
         color: var(--fg);
         background: var(--bg);
         line-height: 1.6;
@@ -200,10 +191,10 @@ const metaDescription = description ?? identity.description;
         overscroll-behavior-x: none;
       }
       h1, h2, h3, h4 {
-        font-family: 'Playfair Display', Georgia, serif;
+        font-family: var(--font-display);
       }
       h1 {
-        font-family: 'Poppins', sans-serif;
+        font-family: var(--font-heading);
         color: var(--fg);
         font-size: clamp(2rem, 0.95rem + 4.5vw, 3.35rem);
         font-weight: 700;
@@ -211,19 +202,15 @@ const metaDescription = description ?? identity.description;
         letter-spacing: -0.01em;
         margin: 0;
       }
-      .site-main h1 {
-        text-align: center;
-      }
       h2 {
-        font-family: 'Playfair Display', Georgia, serif;
+        font-family: var(--font-display);
         color: var(--fg);
         font-size: clamp(1.75rem, 1.45rem + 1vw, 2.25rem);
         line-height: 1.3;
         margin: 0;
-        text-align: center;
       }
       h3 {
-        font-family: 'Poppins', sans-serif;
+        font-family: var(--font-heading);
         color: var(--fg);
         font-size: clamp(1.375rem, 1.2rem + 0.55vw, 1.625rem);
         font-weight: 600;
@@ -231,7 +218,7 @@ const metaDescription = description ?? identity.description;
         margin: 0;
       }
       h4 {
-        font-family: 'Poppins', sans-serif;
+        font-family: var(--font-heading);
         color: var(--accent);
         font-size: clamp(0.6875rem, 0.9vw, 0.75rem);
         font-weight: 500;
@@ -241,7 +228,7 @@ const metaDescription = description ?? identity.description;
       }
 
       p, li {
-        font-family: 'Inter', sans-serif;
+        font-family: var(--font-body);
         color: var(--muted);
         font-size: clamp(1.0625rem, 0.95rem + 0.4vw, 1.25rem);
         font-weight: 400;
@@ -327,7 +314,7 @@ const metaDescription = description ?? identity.description;
         }
       }
       a {
-        font-family: 'Inter', sans-serif;
+        font-family: var(--font-body);
         font-size: clamp(0.875rem, 0.82rem + 0.25vw, 1rem);
         font-weight: 600;
         color: var(--accent);
@@ -397,18 +384,5 @@ const metaDescription = description ?? identity.description;
         .site-main { padding-inline: 1rem; }
       }
     </style>
-
-    <script is:inline>
-      // Remove the "New" flag from posts older than 3 days. Inline so it
-      // runs as soon as it's parsed (before LCP), without an extra request.
-      (function () {
-        var WINDOW = 3 * 24 * 60 * 60 * 1000;
-        var now = Date.now();
-        document.querySelectorAll('.new-flag[data-fresh-since]').forEach(function (el) {
-          var ts = Date.parse(el.getAttribute('data-fresh-since') || '');
-          if (!isNaN(ts) && now - ts >= WINDOW) el.remove();
-        });
-      })();
-    </script>
   </body>
 </html>

package/lib/calendar.ts

@@ -0,0 +1,12 @@
+/**
+ * The calendar capability's data side — a tiny loader so a client's `/calendar`
+ * route stays thin. The consent gate + iframe live in components/CalendarEmbed.astro.
+ */
+import { getEntry } from 'astro:content';
+import { calendarSettingsSchema, type CalendarSettings } from '../content/calendar';
+
+/** Calendar settings (defaults applied, so a missing file is fine). */
+export async function getCalendarSettings(): Promise<CalendarSettings> {
+  const entry = await getEntry('calendarSettings', 'index');
+  return calendarSettingsSchema.parse(entry?.data ?? {});
+}

package/lib/icons.ts

@@ -0,0 +1,64 @@
+/**
+ * The single inline-SVG icon registry for ferst-core (Tier 1a substrate).
+ *
+ * One registry, one shape: each value is the raw markup that goes *inside* an
+ * `<svg>` — see `components/Icon.astro`, the only intended consumer, for the
+ * wrapping attributes. Icons render with `stroke="currentColor"` so they follow
+ * the caller's `color` and switch with the site's light/dark theme automatically.
+ *
+ * Keys are deliberately **business-agnostic** (`landmark`, not `church`;
+ * `map-pin`, not `parish-office`) — this set is part of the reusable substrate.
+ *
+ * History: this merges CTK's two divergent registries (`lib/icons.ts` raw
+ * markup + `lib/tagIcons` structured objects) into one — the seven shapes below
+ * the divider were ported from the tag set (Lucide-derived), converted to the
+ * same markup shape, with duplicates (calendar/heart/tag/people/email/book)
+ * dropped in favour of the entries already here.
+ */
+export const ICONS: Record<string, string> = {
+  landmark: '<path d="M12 3v4M9 7h6M6 21V10l6-4 6 4v11M6 21h12M10 21v-5h4v5"></path>',
+  canopy: '<polygon points="12 3 3 9 21 9"></polygon><line x1="4" y1="9" x2="4" y2="19"></line><line x1="9" y1="9" x2="9" y2="19"></line><line x1="15" y1="9" x2="15" y2="19"></line><line x1="20" y1="9" x2="20" y2="19"></line><line x1="2" y1="22" x2="22" y2="22"></line>',
+  drop: '<path d="M12 3c3 4 6 8.5 6 12a6 6 0 1 1-12 0c0-3.5 3-8 6-12z"></path>',
+  cup: '<path d="M7 4h10M8 4c0 3 .5 6 4 6s4-3 4-6M12 10v7M9 21h6"></path>',
+  flame: '<path d="M12 2c1.5 2.5-1 4-1 6.5a3 3 0 1 0 6 0c0-1-.4-1.8-1-2.3.6 3-1.7 5.3-4 5.3a5 5 0 0 1-5-5c0-3.5 3-4.2 5-4.5z"></path>',
+  heart: '<path d="M12 20s-7-4.2-9.3-8.7A5 5 0 0 1 12 6a5 5 0 0 1 9.3 5.3C19 15.8 12 20 12 20z"></path>',
+  flask: '<path d="M10 3h4M11 3v3.5c0 .5-.2 1-.6 1.4C8.8 9.5 8 11.3 8 13a4 4 0 0 0 8 0c0-1.7-.8-3.5-2.4-5.1a2 2 0 0 1-.6-1.4V3"></path>',
+  link: '<circle cx="9" cy="14" r="5"></circle><circle cx="15" cy="14" r="5"></circle>',
+  document: '<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"></path><path d="M14 2v6h6"></path><line x1="9" y1="13" x2="15" y2="13"></line><line x1="9" y1="17" x2="15" y2="17"></line>',
+  checklist: '<rect x="3" y="4" width="18" height="16" rx="2"></rect><path d="m7 9 2 2 4-4"></path><line x1="13" y1="15" x2="17" y2="15"></line><line x1="7" y1="15" x2="9" y2="15"></line>',
+  people: '<circle cx="12" cy="8" r="3.2"></circle><path d="M5 20c0-3.5 3-6 7-6s7 2.5 7 6"></path>',
+  sparkle: '<path d="M12 3v4M12 17v4M3 12h4M17 12h4M6 6l2 2M16 16l2 2M6 18l2-2M16 8l2-2"></path>',
+  coins: '<ellipse cx="12" cy="6" rx="7" ry="3"></ellipse><path d="M5 6v6c0 1.7 3.1 3 7 3s7-1.3 7-3V6M5 12v6c0 1.7 3.1 3 7 3s7-1.3 7-3v-6"></path>',
+  gift: '<rect x="3.5" y="8" width="17" height="4.5" rx="1"></rect><path d="M5 12.5V19a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2v-6.5"></path><path d="M12 8v13"></path><path d="M12 8H8.2a2.2 2.2 0 1 1 0-4.5C10.8 3.5 12 8 12 8Z"></path><path d="M12 8h3.8a2.2 2.2 0 1 0 0-4.5C13.2 3.5 12 8 12 8Z"></path>',
+  music: '<path d="M9 18V5l12-2v13"></path><circle cx="6" cy="18" r="3"></circle><circle cx="18" cy="16" r="3"></circle>',
+  book: '<path d="M4 19.5V5a2 2 0 0 1 2-2h13v15H6a2 2 0 0 0-2 2Zm0 0a2 2 0 0 0 2 2h13"></path>',
+  calendar: '<rect x="3" y="4" width="18" height="18" rx="2"></rect><line x1="16" y1="2" x2="16" y2="6"></line><line x1="8" y1="2" x2="8" y2="6"></line><line x1="3" y1="10" x2="21" y2="10"></line>',
+  building: '<polyline points="3 11 12 4 21 11"></polyline><rect x="6" y="11" width="12" height="9"></rect><rect x="10" y="15" width="4" height="5"></rect>',
+  shield: '<path d="M12 2 20 5 20 11 C20 16 16.5 20 12 22 C7.5 20 4 16 4 11 L4 5 Z"></path>',
+  tag: '<path d="M20.59 13.41 11 3.83A2 2 0 0 0 9.5 3H4a1 1 0 0 0-1 1v5.5a2 2 0 0 0 .83 1.5l9.58 9.59a2 2 0 0 0 2.83 0l4.35-4.35a2 2 0 0 0 0-2.83z"></path><circle cx="7.5" cy="7.5" r="1.3"></circle>',
+  phone: '<path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07A19.5 19.5 0 0 1 4.69 13a19.79 19.79 0 0 1-3.07-8.67A2 2 0 0 1 3.6 2h3a2 2 0 0 1 2 1.72c.127.96.361 1.903.7 2.81a2 2 0 0 1-.45 2.11L7.91 9.91a16 16 0 0 0 6.18 6.18l1.27-1.27a2 2 0 0 1 2.11-.45c.907.339 1.85.573 2.81.7A2 2 0 0 1 22 16.92z"></path>',
+  email: '<rect x="2" y="4" width="20" height="16" rx="2"></rect><path d="m22 7-8.97 5.7a1.94 1.94 0 0 1-2.06 0L2 7"></path>',
+  chat: '<path d="M20 11.5a7.5 7.5 0 0 1-10.8 6.8L4 19.5l1.2-4.1A7.5 7.5 0 1 1 20 11.5Z"></path><path d="M8.5 11.5h.01M12 11.5h.01M15.5 11.5h.01"></path>',
+  globe: '<circle cx="12" cy="12" r="10"></circle><line x1="2" y1="12" x2="22" y2="12"></line><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"></path>',
+  check: '<path d="M20 6 9 17l-5-5"></path>',
+  arrow: '<path d="M5 12h14M13 6l6 6-6 6"></path>',
+
+  // ── merged from the former tag-icon set (Lucide-derived, ISC) ──────────────
+  megaphone: '<path d="M11 6a13 13 0 0 0 8.4-2.8A1 1 0 0 1 21 4v12a1 1 0 0 1-1.6.8A13 13 0 0 0 11 14H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2z"></path><path d="M6 14a12 12 0 0 0 2.4 7.2 2 2 0 0 0 3.2-2.4A8 8 0 0 1 10 14"></path><path d="M8 6v8"></path>',
+  newspaper: '<path d="M15 18h-5"></path><path d="M18 14h-8"></path><path d="M4 22h16a2 2 0 0 0 2-2V4a2 2 0 0 0-2-2H8a2 2 0 0 0-2 2v16a2 2 0 0 1-4 0v-9a2 2 0 0 1 2-2h2"></path><rect x="10" y="6" width="8" height="4" rx="1"></rect>',
+  star: '<path d="M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z"></path>',
+  bell: '<path d="M10.268 21a2 2 0 0 0 3.464 0"></path><path d="M3.262 15.326A1 1 0 0 0 4 17h16a1 1 0 0 0 .74-1.673C19.41 13.956 18 12.499 18 8A6 6 0 0 0 6 8c0 4.499-1.411 5.956-2.738 7.326"></path>',
+  flag: '<path d="M4 22V4a1 1 0 0 1 .4-.8A6 6 0 0 1 8 2c3 0 5 2 7.333 2q2 0 3.067-.8A1 1 0 0 1 20 4v10a1 1 0 0 1-.4.8A6 6 0 0 1 16 16c-3 0-5-2-8-2a6 6 0 0 0-4 1.528"></path>',
+  'map-pin': '<path d="M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0"></path><circle cx="12" cy="10" r="3"></circle>',
+  'book-open': '<path d="M12 5v16"></path><path d="M20.001 19A2 2 0 0 0 22 17V5a2 2 0 0 0-1.999-2L16 3.002A5 5 0 0 0 12 5a5 5 0 0 0-4-2H4a2 2 0 0 0-2 2v12a2 2 0 0 0 1.999 2H8a5 5 0 0 1 4 2 5 5 0 0 1 4-2z"></path>',
+};
+
+export type IconKey = keyof typeof ICONS;
+
+/** All registry keys, for validation / CMS select generation. */
+export const iconKeys = Object.keys(ICONS) as IconKey[];
+
+/** Runtime guard — true when `value` names an icon in the registry. */
+export function isIconKey(value: unknown): value is IconKey {
+  return typeof value === 'string' && value in ICONS;
+}

package/lib/pages.ts

@@ -0,0 +1,42 @@
+/**
+ * The client block-page renderer's data side. A client's whole site is (chrome
+ * aside) a set of JSON files in the `pages` collection — one file per page, its
+ * filename the URL slug — each an ordered list of typed blocks (content/blocks.ts).
+ * The client's `src/pages/[...slug].astro` catch-all turns these into routes:
+ *
+ *   // src/pages/[...slug].astro  (a real client's is exactly this — thin)
+ *   import Base from 'ferst-core/layouts/Base.astro';
+ *   import BlockRenderer from 'ferst-core/components/BlockRenderer.astro';
+ *   import { pageSchema } from 'ferst-core/content/blocks';
+ *   import { getPageRoutes } from 'ferst-core/lib/pages';
+ *   export const getStaticPaths = getPageRoutes;
+ *   const { entry } = Astro.props;
+ *   const page = pageSchema.parse(entry.data);
+ *   // <Base title={page.title} description={page.description} heroImage={page.heroImage}>
+ *   //   <BlockRenderer blocks={page.blocks} />
+ *   // </Base>
+ *
+ * Keeping this in the core means the routing convention is single-source: a
+ * client repo carries only content + a two-line catch-all, never a copy of the
+ * mechanism. Explicit `.astro` routes always win over the catch-all, so a client
+ * can still hand-build a one-off page beside the JSON-driven ones.
+ */
+import { getCollection } from 'astro:content';
+
+/** All non-draft `pages` entries. */
+export async function getPageEntries() {
+  const all = await getCollection('pages');
+  return all.filter((entry) => !entry.data.draft);
+}
+
+/**
+ * A drop-in `getStaticPaths` for a client's `[...slug].astro`: one route per
+ * non-draft page, keyed by the file's slug, with the entry passed as a prop.
+ */
+export async function getPageRoutes() {
+  const entries = await getPageEntries();
+  return entries.map((entry) => ({
+    params: { slug: entry.id },
+    props: { entry },
+  }));
+}