ferst-core 0.7.10 → 0.7.12

package/components/blocks/ImageBlock.astro

@@ -16,9 +16,10 @@ interface Props {
   shadow?: boolean;
   border?: boolean;
   ratio?: 'auto' | 'square' | '4/3' | '3/2' | '16/9' | '21/9';
+  focus?: string;
   reveal?: boolean;
 }
-const { src, alt = '', caption, radius = 'soft', shadow = false, border = false, ratio = 'auto', reveal = false } = Astro.props;
+const { src, alt = '', caption, radius = 'soft', shadow = false, border = false, ratio = 'auto', reveal = false, focus } = Astro.props;
 const ratioValue = ratio === 'auto' ? null : ratio === 'square' ? '1 / 1' : ratio.replace('/', ' / ');
 ---
 
@@ -34,7 +35,7 @@ const ratioValue = ratio === 'auto' ? null : ratio === 'square' ? '1 / 1' : rati
     alt={alt}
     loading="lazy"
     decoding="async"
-    style={ratioValue ? `aspect-ratio: ${ratioValue}` : undefined}
+    style={ratioValue ? `aspect-ratio: ${ratioValue}${focus ? `; object-position: ${focus}` : ''}` : undefined}
   />
   {caption && <figcaption>{caption}</figcaption>}
 </figure>

package/components/recipes/Bento.astro

@@ -15,7 +15,7 @@ interface Item {
   title: string;
   text?: string;
   href?: string;
-  image?: { src: string; alt?: string };
+  image?: { src: string; alt?: string; focus?: string };
 }
 interface Props {
   title?: string;
@@ -39,7 +39,7 @@ const headAlign = headingAlign ?? blockAlign ?? 'center';
   <div class="b-bento__grid">
     {items.map((item) => {
       const Tag = item.href ? 'a' : 'div';
-      const style = item.variant === 'image' && item.image ? `--bento-image: url('${item.image.src}')` : undefined;
+      const style = item.variant === 'image' && item.image ? `--bento-image: url('${item.image.src}')${item.image.focus ? `; --bento-focus: ${item.image.focus}` : ''}` : undefined;
       return (
         <Tag class="b-bento__item" data-size={item.size ?? 'sm'} data-variant={item.variant ?? 'surface'} href={item.href} style={style}>
           {item.icon && isIconKey(item.icon) && (
@@ -115,7 +115,7 @@ const headAlign = headingAlign ?? blockAlign ?? 'center';
     z-index: -1;
     background-image: linear-gradient(to top, rgba(8,10,18,0.82), rgba(8,10,18,0.15)), var(--bento-image);
     background-size: cover;
-    background-position: center;
+    background-position: center, var(--bento-focus, center);
   }
   a.b-bento__item:hover { transform: translateY(-3px); }
   a.b-bento__item[data-variant='surface']:hover { box-shadow: var(--shadow-lg); }

package/components/recipes/Hero.astro

@@ -46,7 +46,10 @@ const provider = bgLink ? videoEmbed(bgLink)?.provider : undefined;
 const watchLabel = media?.linkLabel || (provider ? `Watch the full video on ${provider}` : 'Watch the full video');
 // The still: the image (no motion), or an embed's poster until the player may load.
 const stillSrc = embed ? media?.poster ?? still : !media?.video && !slides.length ? still : undefined;
-const bgImage = isMedia && stillSrc ? `--hero-image: url('${stillSrc}')` : '';
+// Drawn as a real <img>, never a CSS background: a picture set through a CSS variable is
+// found late (never by the preload scanner), so the hero sat grey until it arrived, and
+// some browsers kept it grey. A real image, loaded first, is found early and painted.
+const heroImg = isMedia && stillSrc ? stillSrc : undefined;
 ---
 
 <section
@@ -58,10 +61,11 @@ const bgImage = isMedia && stillSrc ? `--hero-image: url('${stillSrc}')` : '';
   data-linked={bgLink ? 'true' : undefined}
   data-parallax={isMedia && parallax ? 'true' : undefined}
   data-full-bleed={isMedia && fullBleed ? 'true' : undefined}
-  style={isMedia ? `--hero-overlay: ${overlay}; ${bgImage}${focus ? `; --hero-focus: ${focus}` : ''}` : undefined}
+  style={isMedia ? `--hero-overlay: ${overlay}${focus ? `; --hero-focus: ${focus}` : ''}` : undefined}
 >
   {isMedia && (
     <div class="b-hero__bg" aria-hidden="true">
+      {heroImg && <img class="b-hero__img" src={heroImg} alt="" loading="eager" fetchpriority="high" decoding="async" />}
       {embed && <div class="b-hero__embed" data-embed-url={embed.embedUrl} data-provider={embed.provider}></div>}
       {media?.video && !embed ? (
         <video autoplay muted loop playsinline poster={media.poster} preload="metadata">
@@ -69,7 +73,7 @@ const bgImage = isMedia && stillSrc ? `--hero-image: url('${stillSrc}')` : '';
         </video>
       ) : null}
       {slides.map((src, i) => (
-        <span class:list={['b-hero__slide', { 'is-on': i === 0 }]} style={`background-image: url('${src}')`}></span>
+        <img class:list={['b-hero__slide', { 'is-on': i === 0 }]} src={src} alt="" loading={i === 0 ? 'eager' : 'lazy'} fetchpriority={i === 0 ? 'high' : undefined} decoding="async" />
       ))}
       <span class="b-hero__scrim"></span>
     </div>
@@ -346,11 +350,20 @@ const bgImage = isMedia && stillSrc ? `--hero-image: url('${stillSrc}')` : '';
     position: absolute;
     inset: 0;
     z-index: -1;
-    background-image: var(--hero-image, none);
-    background-size: cover;
-    background-position: var(--hero-focus, center);
     background-color: var(--bg-section);
   }
+  /* The picture (and each rotating slide) covers the band, framed by `focus`. */
+  .b-hero__img,
+  .b-hero__slide {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    object-position: var(--hero-focus, center);
+    display: block;
+    max-width: none;
+  }
   /* Parallax: give the background room to drift without uncovering an edge. */
   .b-hero.is-parallax .b-hero__bg {
     inset: 0 0 -35% 0;
@@ -390,10 +403,6 @@ const bgImage = isMedia && stillSrc ? `--hero-image: url('${stillSrc}')` : '';
     display: none;
   }
   .b-hero__slide {
-    position: absolute;
-    inset: 0;
-    background-size: cover;
-    background-position: var(--hero-focus, center);
     opacity: 0;
     transition: opacity 1.6s ease-in-out;
   }

package/components/recipes/MediaCards.astro

@@ -14,7 +14,7 @@ import Heading from '../blocks/Heading.astro';
 
 import { inlineMarkdown, inlineMarkdownNoLinks } from '../../lib/inline-markdown';
 interface Card {
-  image?: { src: string; alt?: string };
+  image?: { src: string; alt?: string; focus?: string };
   icon?: string;
   title: string;
   meta?: string;
@@ -26,9 +26,10 @@ interface Props {
   title?: string;
   intro?: string;
   columns?: 2 | 3;
+  ratio?: '16/9' | '4/3' | '3/2' | '1/1' | '3/4';
   cards?: Card[];
 }
-const { title, intro, columns = 3, cards = [] } = Astro.props;
+const { title, intro, columns = 3, ratio = '16/9', cards = [] } = Astro.props;
 // Never reserve more columns than there are cards; `data-single` centres a lone one.
 const cols = Math.min(columns, Math.max(cards.length, 1)) as 1 | 2 | 3;
 ---
@@ -49,8 +50,8 @@ const cols = Math.min(columns, Math.max(cards.length, 1)) as 1 | 2 | 3;
       return (
       <article class:list={['b-media-cards__card', 'ferst-tile', 'ferst-tile--sm', card.href && 'is-link']}>
         {card.image && (
-          <div class="b-media-cards__media">
-            <img src={card.image.src} alt={card.image.alt ?? ''} loading="lazy" />
+          <div class="b-media-cards__media" data-ratio={ratio} style={`aspect-ratio: ${ratio.replace('/', ' / ')}`}>
+            <img src={card.image.src} alt={card.image.alt ?? ''} loading="lazy" style={card.image.focus ? `object-position: ${card.image.focus}` : undefined} />
           </div>
         )}
         <div class="b-media-cards__body">

package/components/recipes/MediaText.astro

@@ -1,88 +1,88 @@
----
-/**
- * MediaText — an image beside its text, on the start or end side; stacks (text, then image)
- * on a phone. The text takes prose formatting (paragraphs, lists, links); the image keeps
- * its own shape unless `ratio` sets one (cropped to fill). An optional button follows the
- * text.
- */
-import Heading from '../blocks/Heading.astro';
-import Button from '../Button.astro';
-import ProseParts from '../ProseParts.astro';
-
-interface Props {
-  title?: string;
-  text: string;
-  image: { src: string; alt?: string; caption?: string };
-  imageSide?: 'start' | 'end';
-  ratio?: 'auto' | '1/1' | '4/3' | '3/2' | '16/9';
-  cta?: { label: string; href: string };
-}
-const { title, text, image, imageSide = 'end', ratio = 'auto', cta } = Astro.props;
----
-
-<section class="b-mediatext" data-side={imageSide}>
-  <div class="b-mediatext__text">
-    {title && <Heading text={title} level={2} />}
-    <ProseParts text={text} />
-    {cta && <div class="b-mediatext__cta"><Button href={cta.href} variant="primary">{cta.label}</Button></div>}
-  </div>
-  <figure class="b-mediatext__media">
-    <img src={image.src} alt={image.alt ?? ''} loading="lazy" decoding="async" style={ratio !== 'auto' ? `aspect-ratio: ${ratio}; object-fit: cover` : undefined} />
-    {image.caption && <figcaption>{image.caption}</figcaption>}
-  </figure>
-</section>
-
-<style>
-  .b-mediatext {
-    display: grid;
-    gap: clamp(1.5rem, 4vw, 3rem);
-    align-items: center;
-    width: 100%;
-    max-width: 72rem;
-  }
-  @media (min-width: 48em) {
-    .b-mediatext {
-      grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
-    }
-    .b-mediatext[data-side='start'] .b-mediatext__media {
-      order: -1;
-    }
-  }
-  .b-mediatext__text {
-    display: flex;
-    flex-direction: column;
-    gap: 0.9rem;
-  }
-  .b-mediatext__text :global(p),
-  .b-mediatext__text :global(ul),
-  .b-mediatext__text :global(ol) {
-    margin: 0;
-    line-height: 1.7;
-  }
-  .b-mediatext__text :global(ul),
-  .b-mediatext__text :global(ol) {
-    padding-inline-start: 1.4em;
-  }
-  .b-mediatext__text :global(a:not(.btn)) {
-    color: var(--accent);
-    text-decoration: underline;
-    text-underline-offset: 0.15em;
-  }
-  .b-mediatext__cta {
-    margin-top: 0.4rem;
-  }
-  .b-mediatext__media {
-    margin: 0;
-  }
-  .b-mediatext__media img {
-    display: block;
-    width: 100%;
-    height: auto;
-    border-radius: var(--radius);
-  }
-  .b-mediatext__media figcaption {
-    margin-top: 0.5rem;
-    font-size: 0.875rem;
-    color: var(--muted);
-  }
-</style>
+---
+/**
+ * MediaText — an image beside its text, on the start or end side; stacks (text, then image)
+ * on a phone. The text takes prose formatting (paragraphs, lists, links); the image keeps
+ * its own shape unless `ratio` sets one (cropped to fill). An optional button follows the
+ * text.
+ */
+import Heading from '../blocks/Heading.astro';
+import Button from '../Button.astro';
+import ProseParts from '../ProseParts.astro';
+
+interface Props {
+  title?: string;
+  text: string;
+  image: { src: string; alt?: string; caption?: string; focus?: string };
+  imageSide?: 'start' | 'end';
+  ratio?: 'auto' | '1/1' | '4/3' | '3/2' | '16/9';
+  cta?: { label: string; href: string };
+}
+const { title, text, image, imageSide = 'end', ratio = 'auto', cta } = Astro.props;
+---
+
+<section class="b-mediatext" data-side={imageSide}>
+  <div class="b-mediatext__text">
+    {title && <Heading text={title} level={2} />}
+    <ProseParts text={text} />
+    {cta && <div class="b-mediatext__cta"><Button href={cta.href} variant="primary">{cta.label}</Button></div>}
+  </div>
+  <figure class="b-mediatext__media">
+    <img src={image.src} alt={image.alt ?? ''} loading="lazy" decoding="async" style={ratio !== 'auto' ? `aspect-ratio: ${ratio}; object-fit: cover${image.focus ? `; object-position: ${image.focus}` : ''}` : undefined} />
+    {image.caption && <figcaption>{image.caption}</figcaption>}
+  </figure>
+</section>
+
+<style>
+  .b-mediatext {
+    display: grid;
+    gap: clamp(1.5rem, 4vw, 3rem);
+    align-items: center;
+    width: 100%;
+    max-width: 72rem;
+  }
+  @media (min-width: 48em) {
+    .b-mediatext {
+      grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+    }
+    .b-mediatext[data-side='start'] .b-mediatext__media {
+      order: -1;
+    }
+  }
+  .b-mediatext__text {
+    display: flex;
+    flex-direction: column;
+    gap: 0.9rem;
+  }
+  .b-mediatext__text :global(p),
+  .b-mediatext__text :global(ul),
+  .b-mediatext__text :global(ol) {
+    margin: 0;
+    line-height: 1.7;
+  }
+  .b-mediatext__text :global(ul),
+  .b-mediatext__text :global(ol) {
+    padding-inline-start: 1.4em;
+  }
+  .b-mediatext__text :global(a:not(.btn)) {
+    color: var(--accent);
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+  }
+  .b-mediatext__cta {
+    margin-top: 0.4rem;
+  }
+  .b-mediatext__media {
+    margin: 0;
+  }
+  .b-mediatext__media img {
+    display: block;
+    width: 100%;
+    height: auto;
+    border-radius: var(--radius);
+  }
+  .b-mediatext__media figcaption {
+    margin-top: 0.5rem;
+    font-size: 0.875rem;
+    color: var(--muted);
+  }
+</style>

package/components/recipes/Tiles.astro

@@ -25,7 +25,7 @@ interface Tile {
   text?: string;
   href?: string;
   linkLabel?: string;
-  image?: { src: string; alt?: string };
+  image?: { src: string; alt?: string; focus?: string };
 }
 interface Props {
   title?: string;
@@ -59,7 +59,7 @@ const cols = Math.min(columns, Math.max(tiles.length, 1)) as 1 | 2 | 3 | 4;
       const plain = variant === 'image' && !!tile.image && !tile.title && !tile.text && !tile.eyebrow;
       const bg =
         variant === 'image' && tile.image && !plain
-          ? `--tile-image: url('${tile.image.src}')`
+          ? `--tile-image: url('${tile.image.src}')${tile.image.focus ? `; --tile-focus: ${tile.image.focus}` : ''}`
           : undefined;
       return (
         <Tag
@@ -166,7 +166,7 @@ const cols = Math.min(columns, Math.max(tiles.length, 1)) as 1 | 2 | 3 | 4;
     z-index: -1;
     background-image: linear-gradient(to top, rgba(10, 12, 20, 0.85), rgba(10, 12, 20, 0.15)), var(--tile-image);
     background-size: cover;
-    background-position: center;
+    background-position: center, var(--tile-focus, center);
   }
   /* A picture tile shows the whole image, whatever its shape: no scrim, no crop. */
   .b-tiles__grid[data-variant='image'] .b-tile[data-plain] {

package/content/blocks.ts

@@ -45,6 +45,15 @@ export const proseBlock = z.object({
   variant: z.enum(['body', 'lead']).default('body'),
 });
 
+/** Which part of an image stays in view when it's cropped to a shape: one or two positions,
+ *  keywords or percentages (`center 25%` keeps a face in a portrait, `top`, `left 20%`).
+ *  Positions only, so no other CSS can get in. Default `center`. */
+export const focusPosition = z
+  .string()
+  .regex(/^(?:left|center|right|top|bottom|\d{1,3}%)(?: (?:left|center|right|top|bottom|\d{1,3}%))?$/, 'focus is one or two of left / center / right / top / bottom / a percentage, e.g. "center 25%"');
+/** An image a block may crop to a shape, with the part to keep in view. */
+const croppedImage = z.object({ src: z.string(), alt: z.string().default(''), focus: focusPosition.optional() });
+
 export const imageBlock = z.object({
   type: z.literal('image'),
   enabled: z.boolean().default(true),
@@ -57,6 +66,8 @@ export const imageBlock = z.object({
   shadow: z.boolean().default(false),
   border: z.boolean().default(false),
   ratio: z.enum(['auto', 'square', '4/3', '3/2', '16/9', '21/9']).default('auto'),
+  /** Which part stays in view when `ratio` crops it. */
+  focus: focusPosition.optional(),
   /** Opt in to a soft clip-path reveal as the image scrolls into view
    *  (progressive: no motion under reduced-motion or unsupported browsers). */
   reveal: z.boolean().default(false),
@@ -155,10 +166,7 @@ export const heroBlock = z.object({
   fullBleed: z.boolean().default(false),
   /** Which part of the background image shows when it's cropped: one or two positions,
    *  keywords or percentages (e.g. `center 30%`, `top`, `left 20%`). Default `center`. */
-  focus: z
-    .string()
-    .regex(/^(?:left|center|right|top|bottom|\d{1,3}%)(?: (?:left|center|right|top|bottom|\d{1,3}%))?$/, 'focus is one or two of left / center / right / top / bottom / a percentage, e.g. "center 30%"')
-    .optional(),
+  focus: focusPosition.optional(),
   /** A `media` hero's background drifts more slowly than the page as it scrolls (any
    *  background: image, slides or video). Off on touch devices and under reduced motion. */
   parallax: z.boolean().default(false),
@@ -302,7 +310,7 @@ export const tilesBlock = z.object({
           href: z.string().optional(),
           /** The link cue on a linking tile ("Learn more" by default). */
           linkLabel: z.string().optional(),
-          image: z.object({ src: z.string(), alt: z.string().default('') }).optional(),
+          image: croppedImage.optional(),
         })
         .refine((t) => !!t.title || !!t.image, { message: 'A tile needs a title or an image', path: ['title'] })
     )
@@ -425,7 +433,7 @@ export const bentoBlock = z.object({
         title: z.string(),
         text: z.string().optional(),
         href: z.string().optional(),
-        image: z.object({ src: z.string(), alt: z.string().default('') }).optional(),
+        image: croppedImage.optional(),
       })
     )
     .default([]),
@@ -520,10 +528,12 @@ export const mediaCardsBlock = z.object({
   title: z.string().optional(),
   intro: z.string().optional(),
   columns: z.union([z.literal(2), z.literal(3)]).default(3),
+  /** The image shape: landscape 16:9 (default), 4:3, 3:2, square, or portrait 3:4 (people). */
+  ratio: z.enum(['16/9', '4/3', '3/2', '1/1', '3/4']).default('16/9'),
   cards: z
     .array(
       z.object({
-        image: z.object({ src: z.string(), alt: z.string().default('') }).optional(),
+        image: croppedImage.optional(),
         icon: iconName.optional(),
         title: z.string(),
         /** A short meta line shown as a pill (e.g. "Sundays 10:45 · Main hall"). */
@@ -702,7 +712,7 @@ export const mediaTextBlock = z.object({
   enabled: z.boolean().default(true),
   title: z.string().optional(),
   text: z.string(),
-  image: z.object({ src: z.string(), alt: z.string().default(''), caption: z.string().optional() }),
+  image: z.object({ src: z.string(), alt: z.string().default(''), caption: z.string().optional(), focus: focusPosition.optional() }),
   imageSide: z.enum(['start', 'end']).default('end'),
   ratio: z.enum(['auto', '1/1', '4/3', '3/2', '16/9']).default('auto'),
   cta: z.object({ label: z.string(), href: z.string() }).optional(),

package/layouts/Base.astro

@@ -160,7 +160,9 @@ const metaDescription = description ?? identity.description;
             return;
           }
           if (url.protocol !== 'http:' && url.protocol !== 'https:') return; // skip mailto/tel/etc.
-          if (url.host === host) return; // same-site
+          // Same-site pages stay in the tab; a same-site document (a PDF leaflet, a form)
+          // opens in a new one, like an external link.
+          if (url.host === host && !/\.(?:pdf|docx?|xlsx?|pptx?)$/i.test(url.pathname)) return;
           if (!a.target) a.target = '_blank';
           const rel = new Set((a.getAttribute('rel') || '').split(/\s+/).filter(Boolean));
           rel.add('noopener');

package/lib/inline-markdown.ts

@@ -1,74 +1,79 @@
-/**
- * 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>');
-}
-
-/** Escaped text with single newlines → `<br>`, and no links: for text that already sits
- *  inside a link (a nested <a> is invalid). */
-export function textWithBreaks(text: string | undefined | null): string {
-  return text ? escapeHtml(text).replace(/\n/g, '<br>') : '';
-}
-
-/** Inline formatting (bold, italic, line breaks) WITHOUT links: `[label](href)` becomes
- *  its label. For text inside something that is already a link (a linked tile or card). */
-export function inlineMarkdownNoLinks(text: string | undefined | null): string {
-  return text ? inlineFormat(escapeHtml(text.replace(LINK_RE, '$1'))) : '';
-}
-
-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;
+
+/** A link to a document (PDF, Word, Excel, PowerPoint) opens in a new tab, so a visitor
+ *  doesn't lose the site — as external links already do. */
+export const DOCUMENT_HREF = /\.(?:pdf|docx?|xlsx?|pptx?)(?:[?#]|$)/i;
+
+/** 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>');
+}
+
+/** Escaped text with single newlines → `<br>`, and no links: for text that already sits
+ *  inside a link (a nested <a> is invalid). */
+export function textWithBreaks(text: string | undefined | null): string {
+  return text ? escapeHtml(text).replace(/\n/g, '<br>') : '';
+}
+
+/** Inline formatting (bold, italic, line breaks) WITHOUT links: `[label](href)` becomes
+ *  its label. For text inside something that is already a link (a linked tile or card). */
+export function inlineMarkdownNoLinks(text: string | undefined | null): string {
+  return text ? inlineFormat(escapeHtml(text.replace(LINK_RE, '$1'))) : '';
+}
+
+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)) {
+      const newTab = DOCUMENT_HREF.test(href) ? ' target="_blank" rel="noopener"' : '';
+      out += `<a href="${escapeHtml(href)}"${newTab}>${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;
+}
 
 /** The words of formatted copy with the formatting gone (a link becomes its label): for
  *  places that must be plain text, like a page's meta description. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.7.10",
+  "version": "0.7.12",
   "type": "module",
   "description": "Ferst Core \u2014 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",