ferst-core 0.6.2 → 0.7.0

package/content/cookies.ts

@@ -1,103 +1,112 @@
-/**
- * Cookie / third-party-storage registry + a scanner that reports which uses are
- * actually active on a given site. This powers the auto-generated cookie policy
- * page: its categories and items are DERIVED from the recipes/templates the site
- * uses — functionality-driven, never hand-written or client-specific.
- *
- * Two canonical categories:
- *   • necessary  — the site's OWN functional storage (no third parties). Always
- *                  on; can't be switched off. Present on every site.
- *   • additional — third-party embeds that may set the provider's cookies when
- *                  they load. Gated behind the site's shared embed consent, and
- *                  listed only when a recipe/template that uses them is present.
- *
- * Adding a new cookie-using recipe = one entry here (its `blocks` and/or a
- * detection flag); the policy page then lists it automatically wherever it's used.
- * Pure + framework-free so it's unit-testable without a render.
- */
-
-export type CookieCategory = 'necessary' | 'additional';
-
-export interface CookieUse {
-  /** Stable id (also the consent grouping key in future per-item models). */
-  id: string;
-  category: CookieCategory;
-  /** Human name shown on the policy page, e.g. "Google Maps". */
-  name: string;
-  /** Third-party provider, when applicable. */
-  provider?: string;
-  /** One-line plain-English purpose. */
-  purpose: string;
-  /** What is stored and where. */
-  storage: string;
-}
-
-/** Additional uses carry detection rules; stripped before returning to the view. */
-interface AdditionalUse extends CookieUse {
-  /** Present if any of these block `type`s appears anywhere on the site. */
-  blocks?: string[];
-  /** Present if the site has a Google Calendar configured (a dedicated page). */
-  calendar?: boolean;
-}
-
-/** The site's own functional storage — always present, always on. */
-const NECESSARY: readonly CookieUse[] = [
-  {
-    id: 'consent-choice',
-    category: 'necessary',
-    name: 'Cookie preference',
-    purpose: 'Remembers whether you allowed or declined additional content, so you are not asked again.',
-    storage: 'Stored on your device only (local storage), never shared.',
-  },
-  {
-    id: 'theme',
-    category: 'necessary',
-    name: 'Appearance',
-    purpose: 'Remembers your light or dark theme choice.',
-    storage: 'Stored on your device only (local storage), never shared.',
-  },
-];
-
-/** Third-party embeds — listed only when a site actually uses them. */
-const ADDITIONAL: readonly AdditionalUse[] = [
-  {
-    id: 'google-maps',
-    category: 'additional',
-    name: 'Google Maps',
-    provider: 'Google',
-    purpose: 'Shows embedded maps of where to find us. Google may set cookies when a map loads.',
-    storage: 'Third-party cookies set by Google.',
-    blocks: ['locations', 'mapEmbed'],
-  },
-  {
-    id: 'google-calendar',
-    category: 'additional',
-    name: 'Google Calendar',
-    provider: 'Google',
-    purpose: 'Shows the parish calendar. Google may set cookies when the calendar loads.',
-    storage: 'Third-party cookies set by Google.',
-    blocks: ['calendar'],
-    calendar: true,
-  },
-];
-
-export interface CookieScanInput {
-  /** Every block `type` that appears anywhere on the site. */
-  blockTypes: Iterable<string>;
-  /** True when the site has a Google Calendar configured (dedicated calendar page). */
-  calendarConfigured?: boolean;
-}
-
-export interface CookiePolicyModel {
-  necessary: CookieUse[];
-  additional: CookieUse[];
-}
-
-/** Report the cookie uses actually active on a site, grouped by category. */
-export function scanCookieUses(input: CookieScanInput): CookiePolicyModel {
-  const types = new Set(input.blockTypes);
-  const additional = ADDITIONAL.filter(
-    (u) => (u.blocks?.some((b) => types.has(b)) ?? false) || (u.calendar === true && !!input.calendarConfigured),
-  ).map(({ blocks, calendar, ...use }) => use); // drop detection fields from the view model
-  return { necessary: NECESSARY.map((u) => ({ ...u })), additional };
-}
+/**
+ * Cookie / third-party-storage registry + a scanner that reports which uses are
+ * actually active on a given site. This powers the auto-generated cookie policy
+ * page: its categories and items are DERIVED from the recipes/templates the site
+ * uses — functionality-driven, never hand-written or client-specific.
+ *
+ * Two canonical categories:
+ *   • necessary  — the site's OWN functional storage (no third parties). Always
+ *                  on; can't be switched off. Present on every site.
+ *   • additional — third-party embeds that may set the provider's cookies when
+ *                  they load. Gated behind the site's shared embed consent, and
+ *                  listed only when a recipe/template that uses them is present.
+ *
+ * Adding a new cookie-using recipe = one entry here (its `blocks` and/or a
+ * detection flag); the policy page then lists it automatically wherever it's used.
+ * Pure + framework-free so it's unit-testable without a render.
+ */
+
+export type CookieCategory = 'necessary' | 'additional';
+
+export interface CookieUse {
+  /** Stable id (also the consent grouping key in future per-item models). */
+  id: string;
+  category: CookieCategory;
+  /** Human name shown on the policy page, e.g. "Google Maps". */
+  name: string;
+  /** Third-party provider, when applicable. */
+  provider?: string;
+  /** One-line plain-English purpose. */
+  purpose: string;
+  /** What is stored and where. */
+  storage: string;
+}
+
+/** Additional uses carry detection rules; stripped before returning to the view. */
+interface AdditionalUse extends CookieUse {
+  /** Present if any of these block `type`s appears anywhere on the site. */
+  blocks?: string[];
+  /** Present if the site has a Google Calendar configured (a dedicated page). */
+  calendar?: boolean;
+}
+
+/** The site's own functional storage — always present, always on. */
+const NECESSARY: readonly CookieUse[] = [
+  {
+    id: 'consent-choice',
+    category: 'necessary',
+    name: 'Cookie preference',
+    purpose: 'Remembers whether you allowed or declined additional content, so you are not asked again.',
+    storage: 'Stored on your device only (local storage), never shared.',
+  },
+  {
+    id: 'theme',
+    category: 'necessary',
+    name: 'Appearance',
+    purpose: 'Remembers your light or dark theme choice.',
+    storage: 'Stored on your device only (local storage), never shared.',
+  },
+];
+
+/** Third-party embeds — listed only when a site actually uses them. */
+const ADDITIONAL: readonly AdditionalUse[] = [
+  {
+    id: 'google-maps',
+    category: 'additional',
+    name: 'Google Maps',
+    provider: 'Google',
+    purpose: 'Shows embedded maps of where to find us. Google may set cookies when a map loads.',
+    storage: 'Third-party cookies set by Google.',
+    blocks: ['locations', 'mapEmbed'],
+  },
+  {
+    id: 'google-calendar',
+    category: 'additional',
+    name: 'Google Calendar',
+    provider: 'Google',
+    purpose: 'Shows the parish calendar. Google may set cookies when the calendar loads.',
+    storage: 'Third-party cookies set by Google.',
+    blocks: ['calendar'],
+    calendar: true,
+  },
+  {
+    id: 'video',
+    category: 'additional',
+    name: 'Embedded video (YouTube / Vimeo)',
+    provider: 'Google (YouTube) or Vimeo',
+    purpose: 'Plays videos embedded on our pages. The provider may set cookies when a video loads.',
+    storage: 'Third-party cookies set by the video provider.',
+    blocks: ['video'],
+  },
+];
+
+export interface CookieScanInput {
+  /** Every block `type` that appears anywhere on the site. */
+  blockTypes: Iterable<string>;
+  /** True when the site has a Google Calendar configured (dedicated calendar page). */
+  calendarConfigured?: boolean;
+}
+
+export interface CookiePolicyModel {
+  necessary: CookieUse[];
+  additional: CookieUse[];
+}
+
+/** Report the cookie uses actually active on a site, grouped by category. */
+export function scanCookieUses(input: CookieScanInput): CookiePolicyModel {
+  const types = new Set(input.blockTypes);
+  const additional = ADDITIONAL.filter(
+    (u) => (u.blocks?.some((b) => types.has(b)) ?? false) || (u.calendar === true && !!input.calendarConfigured),
+  ).map(({ blocks, calendar, ...use }) => use); // drop detection fields from the view model
+  return { necessary: NECESSARY.map((u) => ({ ...u })), additional };
+}

package/examples/primitives.ts

@@ -1,28 +1,28 @@
-/** One catalogue entry: a block type, a short description, and a live example. */
-export interface GalleryEntry {
-  type: string;
-  description?: string;
-  block: Record<string, unknown>;
-}
-
-export const primitives: GalleryEntry[] = [
-  { type: 'heading', description: 'A section title, levels 1–6, optionally aligned.', block: { type: 'heading', text: 'A heading', level: 2 } },
-  { type: 'heading', description: 'Optional gradient text — brand → derived accent-2 (falls back to solid ink where unsupported).', block: { type: 'heading', text: 'A gradient heading', level: 2, gradient: true } },
-  { type: 'prose', description: 'Body text; blank lines start new paragraphs.', block: { type: 'prose', text: 'A paragraph of prose.\n\nA second paragraph after a blank line.' } },
-  { type: 'image', description: 'A responsive image with an optional caption. Corners follow the site by default.', block: { type: 'image', src: '/placeholder.svg', alt: 'Placeholder', caption: 'An image with a caption.' } },
-  { type: 'image', description: 'Canonical framing options: soft corners + drop shadow + a fixed 16/9 ratio (image is cover-fit).', block: { type: 'image', src: '/showcase-hero.svg', alt: 'Abstract', radius: 'soft', shadow: true, ratio: '16/9', caption: 'radius: soft · shadow · ratio 16/9' } },
-  { type: 'image', description: 'Square ratio with an outline stroke and sharp corners — same block, different canonical options.', block: { type: 'image', src: '/showcase-hero.svg', alt: 'Abstract', radius: 'none', border: true, ratio: 'square', caption: 'radius: none · stroke · square' } },
-  { type: 'button', description: 'Primary action — the default. Variant is a role, not decoration; corner shape follows the global radius knob.', block: { type: 'button', label: 'Primary', href: '#' } },
-  { type: 'button', description: 'Secondary action — a quieter outline button.', block: { type: 'button', label: 'Secondary', href: '#', variant: 'secondary' } },
-  { type: 'button', description: 'Filled CTA — the brand-accent call to action.', block: { type: 'button', label: 'Get started', href: '#', variant: 'cta' } },
-  { type: 'button', description: 'Ghost — a quiet, borderless text button for tertiary actions.', block: { type: 'button', label: 'Learn more', href: '#', variant: 'ghost' } },
-  { type: 'quote', description: 'A pull quote with an optional citation.', block: { type: 'quote', text: 'A memorable quotation, set apart.', cite: 'Someone' } },
-  { type: 'divider', description: 'A horizontal rule between sections.', block: { type: 'divider' } },
-  { type: 'spacer', description: 'Vertical space (sm / md / lg) — invisible by design.', block: { type: 'spacer', size: 'lg' } },
-  { type: 'section', description: 'A full-width band (background + width) holding child blocks.', block: { type: 'section', background: 'muted', width: 'normal', blocks: [{ type: 'heading', text: 'Inside a section', level: 3 }, { type: 'prose', text: 'Sections hold child blocks.' }] } },
-  { type: 'grid', description: 'A responsive N-column grid of child blocks.', block: { type: 'grid', columns: 3, blocks: [{ type: 'prose', text: 'Column one' }, { type: 'prose', text: 'Column two' }, { type: 'prose', text: 'Column three' }] } },
-  { type: 'stack', description: 'Stacks child blocks vertically with a consistent gap.', block: { type: 'stack', gap: 'sm', blocks: [{ type: 'prose', text: 'Stacked one' }, { type: 'prose', text: 'Stacked two' }] } },
-  { type: 'badge', description: 'A small pill label (accent or neutral tone).', block: { type: 'badge', text: 'New', tone: 'accent' } },
-  { type: 'stat', description: 'A headline number with a label.', block: { type: 'stat', value: '250+', label: 'families served' } },
-  { type: 'list', description: 'A bulleted, numbered, or checked list of lines.', block: { type: 'list', style: 'check', items: ['Everything shares one design language', 'Your brand, applied consistently', 'You own the output'] } },
-];
+/** One catalogue entry: a block type, a short description, and a live example. */
+export interface GalleryEntry {
+  type: string;
+  description?: string;
+  block: Record<string, unknown>;
+}
+
+export const primitives: GalleryEntry[] = [
+  { type: 'heading', description: 'A section title, levels 1–6, optionally aligned.', block: { type: 'heading', text: 'A heading', level: 2 } },
+  { type: 'heading', description: 'Optional gradient text — brand → derived accent-2 (falls back to solid ink where unsupported).', block: { type: 'heading', text: 'A gradient heading', level: 2, gradient: true } },
+  { type: 'prose', description: 'Body text: blank lines start new paragraphs, `- ` / `1. ` lines make lists, and inline links (incl. phone and email), bold and italic render safely.', block: { type: 'prose', text: 'A paragraph of prose with **bold**, *italic* and a [link to the recipes](/recipes).\n\nFor a quick answer, [phone the office](tel:01234567890).\n\n- Lists from simple lines\n- With a [link](/primitives) inside' } },
+  { type: 'image', description: 'A responsive image with an optional caption. Corners follow the site by default.', block: { type: 'image', src: '/placeholder.svg', alt: 'Placeholder', caption: 'An image with a caption.' } },
+  { type: 'image', description: 'Canonical framing options: soft corners + drop shadow + a fixed 16/9 ratio (image is cover-fit).', block: { type: 'image', src: '/showcase-hero.svg', alt: 'Abstract', radius: 'soft', shadow: true, ratio: '16/9', caption: 'radius: soft · shadow · ratio 16/9' } },
+  { type: 'image', description: 'Square ratio with an outline stroke and sharp corners — same block, different canonical options.', block: { type: 'image', src: '/showcase-hero.svg', alt: 'Abstract', radius: 'none', border: true, ratio: 'square', caption: 'radius: none · stroke · square' } },
+  { type: 'button', description: 'Primary action — the default. Variant is a role, not decoration; corner shape follows the global radius knob.', block: { type: 'button', label: 'Primary', href: '#' } },
+  { type: 'button', description: 'Secondary action — a quieter outline button.', block: { type: 'button', label: 'Secondary', href: '#', variant: 'secondary' } },
+  { type: 'button', description: 'Filled CTA — the brand-accent call to action.', block: { type: 'button', label: 'Get started', href: '#', variant: 'cta' } },
+  { type: 'button', description: 'Ghost — a quiet, borderless text button for tertiary actions.', block: { type: 'button', label: 'Learn more', href: '#', variant: 'ghost' } },
+  { type: 'quote', description: 'A pull quote with an optional citation.', block: { type: 'quote', text: 'A memorable quotation, set apart.', cite: 'Someone' } },
+  { type: 'divider', description: 'A horizontal rule between sections.', block: { type: 'divider' } },
+  { type: 'spacer', description: 'Vertical space (sm / md / lg) — invisible by design.', block: { type: 'spacer', size: 'lg' } },
+  { type: 'section', description: 'A full-width band (background + width) holding child blocks.', block: { type: 'section', background: 'muted', width: 'normal', blocks: [{ type: 'heading', text: 'Inside a section', level: 3 }, { type: 'prose', text: 'Sections hold child blocks.' }] } },
+  { type: 'grid', description: 'A responsive N-column grid of child blocks.', block: { type: 'grid', columns: 3, blocks: [{ type: 'prose', text: 'Column one' }, { type: 'prose', text: 'Column two' }, { type: 'prose', text: 'Column three' }] } },
+  { type: 'stack', description: 'Stacks child blocks vertically with a consistent gap.', block: { type: 'stack', gap: 'sm', blocks: [{ type: 'prose', text: 'Stacked one' }, { type: 'prose', text: 'Stacked two' }] } },
+  { type: 'badge', description: 'A small pill label (accent or neutral tone).', block: { type: 'badge', text: 'New', tone: 'accent' } },
+  { type: 'stat', description: 'A headline number with a label.', block: { type: 'stat', value: '250+', label: 'families served' } },
+  { type: 'list', description: 'A bulleted, numbered, or checked list of lines.', block: { type: 'list', style: 'check', items: ['Everything shares one design language', 'Your brand, applied consistently', 'You own the output'] } },
+];

package/examples/recipes.ts

@@ -3,6 +3,7 @@ import type { GalleryEntry } from './primitives';
 export const recipes: GalleryEntry[] = [
   { type: 'hero', description: 'Page-opening band — centred preset.', block: { type: 'hero', eyebrow: 'Recipe', title: 'Hero (centered)', subtitle: 'A curated opening band composing Heading + Button.', cta: { label: 'Primary action', href: '#' }, layout: 'centered' } },
   { type: 'hero', description: 'Page-opening band — split preset (text beside image).', block: { type: 'hero', title: 'Hero (split)', subtitle: 'Text beside an image.', cta: { label: 'Primary action', href: '#' }, image: { src: '/placeholder.svg', alt: 'Placeholder' }, layout: 'split' } },
+  { type: 'hero', description: 'Media preset with a slow crossfade through several images — pauses off-screen, has a pause button, and stays on the first image under reduced motion. A single image is a still background; a `video` loops instead (and `size: "screen"` fills the first screen, edge to edge).', block: { type: 'hero', eyebrow: 'Welcome', title: 'Hero (media, rotating images)', subtitle: 'Text over a background that changes slowly.', cta: { label: 'Primary action', href: '#' }, layout: 'media', size: 'tall', media: { images: ['/showcase-hero.svg', '/placeholder.svg'], overlay: 45 } } },
   { type: 'featureCards', description: 'An optional header over a responsive grid of icon + title + text cards.', block: { type: 'featureCards', title: 'Feature cards', columns: 3, cards: [{ icon: 'book-open', title: 'First feature', text: 'A short description.' }, { icon: 'shield', title: 'Second feature', text: 'A short description.' }, { icon: 'sparkle', title: 'Third feature', text: 'A short description.' }] } },
   { type: 'cta', description: 'A centred call-to-action band (heading + text + button).', block: { type: 'cta', title: 'Ready to start?', text: 'A closing nudge with a single, clear action.', cta: { label: 'Get in touch', href: '#' }, background: 'accent' } },
   { type: 'faq', description: 'Expandable question / answer list — native, accessible, no JavaScript.', block: { type: 'faq', title: 'Frequently asked', items: [{ question: 'How are pages built?', answer: 'From a curated set of blocks, composed into your pages and verified before they go live — see the [architecture notes](https://example.com/architecture).' }, { question: 'Can I use my own brand?', answer: 'Yes — colours and fonts are your config; the core is brand-agnostic.' }] } },
@@ -13,6 +14,7 @@ export const recipes: GalleryEntry[] = [
   { type: 'tiles', description: 'A card grid with five looks — here “elevated” (soft shadow, lifts on hover) with the optional pointer-following spotlight. Radius / stroke / elevation come from the global surface tokens.', block: { type: 'tiles', variant: 'elevated', columns: 3, spotlight: true, tiles: [{ icon: 'sparkle', eyebrow: 'Level 1', title: 'Primitives', text: 'The raw ingredients.', href: '#' }, { icon: 'book-open', eyebrow: 'Level 2', title: 'Recipes', text: 'Curated compositions.', href: '#' }, { icon: 'shield', eyebrow: 'Level 3', title: 'Templates', text: 'Whole pages.', href: '#' }] } },
   { type: 'tiles', description: 'The “gradient” variant — brand → a derived accent-2 (an OKLCH hue-shift of your one brand colour), light text.', block: { type: 'tiles', variant: 'gradient', columns: 3, tiles: [{ icon: 'flame', title: 'Vibrant', text: 'One brand colour, a harmonious gradient.' }, { icon: 'sparkle', title: 'Derived', text: 'Accent-2 is computed, not configured.' }, { icon: 'heart', title: 'On-brand', text: 'Always harmonises with your hue.' }] } },
   { type: 'tiles', description: 'The “image” variant — a full-bleed photo with a legibility scrim and light text; the whole tile links.', block: { type: 'tiles', variant: 'image', columns: 3, tiles: [{ eyebrow: 'Feature', title: 'Photo tile', text: 'Text stays legible over any image.', href: '#', image: { src: '/placeholder.svg', alt: 'Placeholder' } }, { title: 'Second', text: 'Cover-fit background.', href: '#', image: { src: '/placeholder.svg', alt: 'Placeholder' } }, { title: 'Third', text: 'With a gradient scrim.', href: '#', image: { src: '/placeholder.svg', alt: 'Placeholder' } }] } },
+  { type: 'tiles', description: 'Picture tiles — the “image” variant with no words: the picture alone is the tile (and the button, when it links), named by its alt text. Mix with worded tiles; `linkLabel` sets the cue.', block: { type: 'tiles', variant: 'image', columns: 3, tiles: [{ href: '#', image: { src: '/placeholder.svg', alt: 'Summer fair poster — details' } }, { href: '#', image: { src: '/placeholder.svg', alt: 'Partner charity — visit their site' } }, { title: 'Newsletters', text: 'Every issue, newest first.', href: '#', linkLabel: 'Read them', image: { src: '/placeholder.svg', alt: '' } }] } },
   { type: 'banner', description: 'A full-bleed feature band — a fixed/parallax background image with a scrim and a floating “shaded glass” card. Pure-CSS parallax; disabled on touch and under reduced-motion.', block: { type: 'banner', image: '/showcase-hero.svg', eyebrow: 'Featured', title: 'A banner that moves', text: 'The image is pinned to the viewport, so it drifts under this card as you scroll.', cta: { label: 'Take a look', href: '#' }, align: 'start' } },
   { type: 'stats', description: 'A band of headline numbers (value + label) over an optional heading — social proof at a glance.', block: { type: 'stats', title: 'By the numbers', background: 'muted', columns: 3, items: [{ value: '250+', label: 'projects shipped' }, { value: '99.9%', label: 'uptime', description: 'rolling 12 months' }, { value: '<1 day', label: 'average reply' }] } },
   { type: 'steps', description: 'A numbered process — connected cards (horizontal) or a stacked timeline (vertical).', block: { type: 'steps', title: 'How it works', layout: 'horizontal', items: [{ icon: 'chat', title: 'Tell us the problem', text: 'A straight conversation about the work costing you time.' }, { icon: 'sparkle', title: 'We fit it to you', text: 'The platform, shaped around how you actually work.' }, { icon: 'shield', title: 'You run it', text: 'Yours to use; we keep it running.' }] } },
@@ -29,4 +31,6 @@ export const recipes: GalleryEntry[] = [
   { type: 'mediaCards', description: 'Rich content cards with the image as a HEADER on top (cover-cropped) + an icon badge, title, meta pill, description and CTA — the image and copy both stay fully legible (unlike the tiles image variant, which puts the image behind the text). For groups, team, services or events.', block: { type: 'mediaCards', title: 'Get involved', intro: 'Cards whose photo and copy both need to read clearly.', columns: 3, cards: [{ image: { src: '/placeholder.svg', alt: '' }, icon: 'heart', title: 'Prayer Group', meta: 'Sundays 10:45 · Parish hall', text: 'Praying together before the Sunday service — newcomers always welcome.', href: '#', linkLabel: 'Find out more' }, { image: { src: '/placeholder.svg', alt: '' }, icon: 'people', title: 'Community League', meta: 'First Wednesday · 7pm', text: 'Faith, friendship, service and mission.', href: '#' }, { image: { src: '/placeholder.svg', alt: '' }, icon: 'globe', title: 'Partner Community', meta: 'Your area', text: 'A neighbouring community we work closely with.', href: '#', linkLabel: 'Visit their site' }] } },
   { type: 'contactCard', description: 'A branded "get in touch" band — a theme-adaptive panel (a section surface with a soft brand-gold corner wash) carrying a display-type title + subtitle on the left, contact channels as tappable tiles on the right, and a closing note across the bottom. Composes in both light and dark. The polished alternative to a plain notice box.', block: { type: 'contactCard', eyebrow: 'Parish office', title: 'Get in touch', subtitle: 'Parish Priest: Fr John Doe', note: 'For a quick reply, phone the office directly — email is best for non-urgent matters.', items: [{ icon: 'phone', value: '01234 567890', href: 'tel:01234567890' }, { icon: 'email', value: 'office@st-placeholder.example', href: 'mailto:office@st-placeholder.example' }, { icon: 'link', value: 'Follow us on Facebook', href: 'https://facebook.com/' }] } },
   { type: 'locations', description: 'A "where to find us" grid — one or more places, each a neat tile with a consent-gated map on top and its name / address / directions below. Maps load once the visitor accepts the site cookie banner (shared consent, no per-tile gate). Replaces stacking bare map embeds.', block: { type: 'locations', title: 'Where to find us', columns: 2, items: [{ name: "St Placeholder's", address: '1 Example Street\nPlaceholdertown EX4 3PL', embedUrl: 'https://www.google.com/maps/embed?pb=!demo1', directionsUrl: 'https://maps.google.com/' }, { name: "St Sample's", address: '2 Sample Road\nPlaceholdertown', embedUrl: 'https://www.google.com/maps/embed?pb=!demo2', directionsUrl: 'https://maps.google.com/' }] } },
+  { type: 'video', description: 'A consent-gated video — paste an ordinary YouTube (incl. a channel’s live page) or Vimeo link; it plays through the privacy-friendly embed only once the visitor agrees, with a “watch on YouTube” alternative. Fixed ratio, never overflows.', block: { type: 'video', title: 'Watch', caption: 'Sample video link.', url: 'https://www.youtube.com/watch?v=aqz-KE-bpKQ', ratio: '16/9' } },
+  { type: 'documents', description: 'A list of files — newsletters, minutes, policies, forms — newest first, optionally grouped by year: type badge, title, date and note per row. Opens in the browser’s own viewer rather than an in-page one (better on phones).', block: { type: 'documents', title: 'Newsletters', intro: 'Every issue, newest first.', groupByYear: true, items: [{ title: 'Newsletter — Advent', file: '/files/sample-advent.pdf', date: '2026-11-30' }, { title: 'Newsletter — Harvest', file: '/files/sample-harvest.pdf', date: '2026-10-04', note: 'Includes the harvest appeal' }, { title: 'Newsletter — Christmas', file: '/files/sample-christmas.pdf', date: '2025-12-21' }, { title: 'Hall hire form', file: '/files/sample-hire-form.docx' }] } },
 ];

package/lib/documents.ts

@@ -0,0 +1,62 @@
+/**
+ * The `documents` block's list logic: newest first (dated items by date, undated ones
+ * after, in the order given), an optional grouping by year, a file-type label from the
+ * extension, and a readable date. Pure — the component only renders the result.
+ */
+export interface DocumentItem {
+  title: string;
+  file: string;
+  date?: string;
+  note?: string;
+}
+export interface DocumentRow extends DocumentItem {
+  kind: string;
+  dateLabel?: string;
+}
+export interface DocumentGroup {
+  year: string | null;
+  items: DocumentRow[];
+}
+
+const KINDS: Record<string, string> = {
+  pdf: 'PDF', doc: 'Word', docx: 'Word', xls: 'Excel', xlsx: 'Excel', csv: 'CSV',
+  ppt: 'PowerPoint', pptx: 'PowerPoint', odt: 'Document', rtf: 'Document', txt: 'Text',
+  jpg: 'Image', jpeg: 'Image', png: 'Image', zip: 'ZIP',
+};
+
+export function fileKind(file: string): string {
+  const ext = file.split(/[?#]/)[0].split('.').pop()?.toLowerCase() ?? '';
+  return KINDS[ext] ?? 'File';
+}
+
+/** A valid ISO-ish date (YYYY-MM-DD…) → a Date, else null. */
+function parseDate(d: string | undefined): Date | null {
+  if (!d || !/^\d{4}-\d{2}-\d{2}/.test(d)) return null;
+  const t = new Date(d.slice(0, 10) + 'T00:00:00Z');
+  return Number.isNaN(t.getTime()) ? null : t;
+}
+
+export function documentGroups(items: DocumentItem[], groupByYear = false): DocumentGroup[] {
+  const rows = items.map((item, i) => {
+    const d = parseDate(item.date);
+    return {
+      row: {
+        ...item,
+        kind: fileKind(item.file),
+        dateLabel: d ? d.toLocaleDateString('en-GB', { day: 'numeric', month: 'long', year: 'numeric', timeZone: 'UTC' }) : undefined,
+      } as DocumentRow,
+      time: d?.getTime() ?? null,
+      year: d ? String(d.getUTCFullYear()) : null,
+      i,
+    };
+  });
+  rows.sort((a, b) => (a.time !== null && b.time !== null ? b.time - a.time : a.time !== null ? -1 : b.time !== null ? 1 : a.i - b.i));
+  if (!groupByYear) return [{ year: null, items: rows.map((r) => r.row) }];
+  const groups: DocumentGroup[] = [];
+  for (const r of rows) {
+    const last = groups[groups.length - 1];
+    if (last && last.year === r.year) last.items.push(r.row);
+    else groups.push({ year: r.year, items: [r.row] });
+  }
+  return groups;
+}

package/lib/inline-markdown.ts

@@ -1,52 +1,59 @@
-/**
- * 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;
-}
+/**
+ * inlineMarkdown — render a *tiny*, safe subset of markdown from trusted editor/CMS
+ * text: links `[label](href)`, bold `**text**`, italic `*text*` / `_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, italic + single-newline breaks, applied to already-escaped text. Italic
+ *  `*x*` / `_x_` must hug its text, and `_` only counts at word edges, so
+ *  snake_case and a lone asterisk stay literal. */
+function inlineFormat(escaped: string): string {
+  return escaped
+    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+    .replace(/(^|[^*\w])\*(?![\s*])([^*]*?[^\s*])\*(?!\*)/g, '$1<em>$2</em>')
+    .replace(/(^|[^\w])_(?![\s_])([^_]*?[^\s_])_(?!\w)/g, '$1<em>$2</em>')
+    .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/prose.ts

@@ -0,0 +1,29 @@
+/**
+ * Prose → paragraphs and simple lists, for the `prose` block. Blank lines separate
+ * paragraphs; a paragraph whose every line starts `- ` / `* ` becomes a bulleted list,
+ * and one whose every line starts `1. ` / `1) ` a numbered list. Inline formatting
+ * (links incl. tel:/mailto:, bold, italic) comes from inlineMarkdown, which escapes
+ * everything first — so the output is safe for `set:html`.
+ */
+import { inlineMarkdown } from './inline-markdown';
+
+export type ProsePart =
+  | { kind: 'p'; html: string }
+  | { kind: 'ul' | 'ol'; items: string[] };
+
+const BULLET = /^\s*[-*•]\s+/;
+const NUMBER = /^\s*\d+[.)]\s+/;
+
+export function proseParts(text: string | undefined | null): ProsePart[] {
+  if (!text) return [];
+  return text
+    .split(/\n\s*\n/)
+    .map((p) => p.trim())
+    .filter(Boolean)
+    .map((p): ProsePart => {
+      const lines = p.split('\n').map((l) => l.trim()).filter(Boolean);
+      if (lines.every((l) => BULLET.test(l))) return { kind: 'ul', items: lines.map((l) => inlineMarkdown(l.replace(BULLET, ''))) };
+      if (lines.length > 1 && lines.every((l) => NUMBER.test(l))) return { kind: 'ol', items: lines.map((l) => inlineMarkdown(l.replace(NUMBER, ''))) };
+      return { kind: 'p', html: inlineMarkdown(p) };
+    });
+}

package/lib/video.ts

@@ -0,0 +1,56 @@
+/**
+ * Video links → a privacy-friendly embed. Accepts what an editor would paste — a
+ * YouTube watch / share / shorts / live link, a channel's live page, or a Vimeo link —
+ * and returns the embed URL (youtube-nocookie / Vimeo `dnt=1`) plus a link to watch it
+ * on the provider. Anything else → null (the block shows a plain link instead).
+ */
+export interface VideoEmbed {
+  provider: 'YouTube' | 'Vimeo';
+  embedUrl: string;
+  watchUrl: string;
+}
+
+const YT_ID = /^[A-Za-z0-9_-]{11}$/;
+const YT_CHANNEL = /^UC[A-Za-z0-9_-]{22}$/;
+
+export function videoEmbed(input: string | undefined | null): VideoEmbed | null {
+  if (!input) return null;
+  let u: URL;
+  try {
+    u = new URL(input.trim());
+  } catch {
+    return null;
+  }
+  if (u.protocol !== 'https:') return null;
+  const host = u.hostname.replace(/^(www\.|m\.)/, '');
+  const parts = u.pathname.split('/').filter(Boolean);
+  const watchUrl = u.toString();
+
+  if (host === 'youtu.be' && YT_ID.test(parts[0] ?? '')) return yt(parts[0], watchUrl);
+  if (host === 'youtube.com' || host === 'youtube-nocookie.com') {
+    const v = u.searchParams.get('v');
+    if (parts[0] === 'watch' && v && YT_ID.test(v)) return yt(v, watchUrl);
+    if (['embed', 'shorts', 'live', 'v'].includes(parts[0]) && YT_ID.test(parts[1] ?? '')) return yt(parts[1], watchUrl);
+    // A channel's live stream: /channel/<UC…>/live, or an embed of live_stream?channel=…
+    const channel = parts[0] === 'channel' && parts[2] === 'live' ? parts[1] : u.searchParams.get('channel');
+    if (channel && YT_CHANNEL.test(channel)) {
+      return {
+        provider: 'YouTube',
+        embedUrl: `https://www.youtube.com/embed/live_stream?channel=${channel}`,
+        watchUrl: `https://www.youtube.com/channel/${channel}/live`,
+      };
+    }
+    return null;
+  }
+  if (host === 'vimeo.com' && /^\d+$/.test(parts[0] ?? '')) {
+    return { provider: 'Vimeo', embedUrl: `https://player.vimeo.com/video/${parts[0]}?dnt=1`, watchUrl };
+  }
+  if (host === 'player.vimeo.com' && parts[0] === 'video' && /^\d+$/.test(parts[1] ?? '')) {
+    return { provider: 'Vimeo', embedUrl: `https://player.vimeo.com/video/${parts[1]}?dnt=1`, watchUrl: `https://vimeo.com/${parts[1]}` };
+  }
+  return null;
+}
+
+function yt(id: string, watchUrl: string): VideoEmbed {
+  return { provider: 'YouTube', embedUrl: `https://www.youtube-nocookie.com/embed/${id}?rel=0`, watchUrl };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.6.2",
+  "version": "0.7.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",