@bygghammar/cms-platform 0.80.1 → 0.90.0-m7.10

package/src/site/routes.ts

@@ -16,6 +16,7 @@
  */
 
 import { DEFAULT_LOCALE, SUPPORTED_LOCALES, type Locale } from "../i18n/locales";
+import { domainOrigin, isValidCanonicalDomain } from "./host";
 import type { Localized, LocalizedImage, LocalizedString } from "../i18n/types";
 import { t, tv } from "../i18n/resolve";
 
@@ -124,27 +125,162 @@ export function fallbackPageDef(pageKey: string): PageDef {
   };
 }
 
+/**
+ * The absolute origin `locale` is served from, or "" when it has none.
+ *
+ * A row whose domain is not a usable hostname is skipped rather than returned,
+ * and the scan continues: mappings written before the backoffice validated
+ * them are still in the table, and one bad row must not hide a good one for
+ * the same language.
+ */
 function originForLocale(locale: Locale, domains: RouteLocaleDomain[]): string {
-  const match = domains.find((d) => d.locale === locale);
-  if (!match) return "";
-  const domain = match.domain.replace(/^https?:\/\//, "").replace(/\/+$/, "");
-  return `https://${domain}`;
+  for (const d of domains) {
+    if (d.locale !== locale) continue;
+    const mapped = domainOrigin(d.domain);
+    if (mapped) return mapped;
+  }
+  return "";
+}
+
+/**
+ * A caller-supplied origin reduced to `scheme://host[:port]`, or "" when the
+ * value cannot be one.
+ *
+ * Sitemaps are the reason this exists. Their serializer writes `<loc>` exactly
+ * as handed to it, so a missing origin does not degrade into a relative URL —
+ * it produces `<loc>/en/about</loc>`, which is not a location at all. An
+ * unusable origin yields "" here and the sitemap is then empty, which a
+ * crawler can at least read correctly.
+ */
+export function publicOrigin(value: string | null | undefined): string {
+  const raw = (value ?? "").trim().replace(/\/+$/, "");
+  if (!/^https?:\/\//i.test(raw)) return "";
+  try {
+    return new URL(raw).origin;
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * The origin the page's own canonical URL is built from.
+ *
+ * Request matching and canonical output are different jobs. A request that
+ * arrives on `voyara.se` when the Swedish mapping stores `www.voyara.se` is
+ * served — the matcher folds apex and one `www.` together on purpose — but the
+ * canonical it publishes is the *stored* hostname, so the alias does not
+ * become a second indexable address for the same page.
+ *
+ * When the current locale has no valid mapping the request origin remains the
+ * answer: a preview host, or a language this deployment serves without giving
+ * it a domain, still renders a real page that still needs a canonical.
+ */
+function canonicalOrigin(
+  locale: Locale,
+  domains: RouteLocaleDomain[],
+  origin: string,
+): string {
+  return originForLocale(locale, domains) || origin;
 }
 
 /**
- * Build the sitemap index entries — one sitemap URL per configured domain.
- * Independent of any page registry.
+ * Origin an alternate for `locale` may use, or null when it may not have one.
+ *
+ * The domain table decides which of two modes the deployment is in.
+ *
+ * SINGLE-ORIGIN MODE (`domains.length === 0`)
+ *   Nothing is mapped, so every language is served from the one hostname the
+ *   request arrived on, under locale-prefixed routes — `https://example.com/`
+ *   and `https://example.com/en`. The current origin is the honest answer for
+ *   all of them, and this is the behaviour the CMS has always had.
+ *
+ * EXPLICIT DOMAIN-MAPPING MODE (`domains.length > 0`)
+ *   The mappings are authoritative. A locale earns an hreflang link, a sitemap
+ *   alternate and a locale-specific absolute origin by having a domain of its
+ *   own, and a locale missing from a non-empty table gets none of the three —
+ *   never a fall back to the current origin. That fall back is what this used
+ *   to do, and it invents the URL: a site that maps Swedish to its domain and
+ *   supports English without one published `https://<swedish domain>/en/...`,
+ *   an address that answers 404, offered to crawlers as the English page.
+ *
+ * A missing alternate costs nothing. A wrong one costs the page.
  */
-export function sitemapIndexEntries(domains: RouteLocaleDomain[] = []): Array<{
+function alternateOrigin(
+  locale: Locale,
+  domains: RouteLocaleDomain[],
+  origin: string,
+): string | null {
+  if (domains.length === 0) return origin;
+  return originForLocale(locale, domains) || null;
+}
+
+/**
+ * The locale and origin `x-default` should point at, or null when it must be
+ * omitted.
+ *
+ * In explicit domain-mapping mode the answer comes from the mapping table, not
+ * from the compiled `DEFAULT_LOCALE`: the deployment states which of its
+ * domains is the fallback by flagging it, and a site whose only mapping is
+ * `en -> voyara.com` has an English x-default however the package was built.
+ * Reading the compiled constant instead pointed x-default at a locale the
+ * deployment never mapped, which is the same fabricated origin the alternates
+ * were just taught to refuse.
+ *
+ * In single-origin mode there is no table to ask, so the site's own default
+ * locale is the answer — served, like every other locale, from this origin.
+ *
+ * Either way the page must actually publish that locale. Nothing is invented
+ * to fill the slot; the link is simply left out.
+ */
+function xDefaultTarget(
+  domains: RouteLocaleDomain[],
+  origin: string,
+  localesForPage: Locale[],
+): { locale: Locale; origin: string } | null {
+  if (domains.length === 0) {
+    return localesForPage.includes(DEFAULT_LOCALE) ? { locale: DEFAULT_LOCALE, origin } : null;
+  }
+  for (const mapping of domains) {
+    if (mapping.isDefault !== true) continue;
+    if (!isValidCanonicalDomain(mapping.domain)) continue;
+    const mapped = domainOrigin(mapping.domain);
+    if (!mapped) continue;
+    const locale = mapping.locale as Locale;
+    if (!localesForPage.includes(locale)) continue;
+    return { locale, origin: mapped };
+  }
+  return null;
+}
+
+/**
+ * Build the sitemap index entries. Independent of any page registry.
+ *
+ * In explicit domain-mapping mode that is one sitemap URL per configured
+ * domain, with unusable rows dropped rather than turned into
+ * `/sitemap/sv.xml` on no host at all.
+ *
+ * In single-origin mode — no rows, one hostname serving every language under
+ * locale prefixes — the index is built from `origin` and `locales` instead.
+ * Returning nothing there was wrong: those per-locale sitemaps exist and are
+ * reachable, and an empty index is a claim that they are not.
+ */
+export function sitemapIndexEntries(
+  domains: RouteLocaleDomain[] = [],
+  origin: string = "",
+  locales: Locale[] = [...SUPPORTED_LOCALES],
+): Array<{
   locale: Locale;
   url: string;
 }> {
-  return domains.map((d) => {
-    const domain = d.domain.replace(/^https?:\/\//, "").replace(/\/+$/, "");
-    return {
-      locale: d.locale as Locale,
-      url: `https://${domain}/sitemap/${d.locale}.xml`,
-    };
+  if (domains.length === 0) {
+    const base = publicOrigin(origin);
+    if (!base) return [];
+    return locales.map((l) => ({ locale: l, url: `${base}/sitemap/${l}.xml` }));
+  }
+  return domains.flatMap((d) => {
+    const mapped = domainOrigin(d.domain);
+    if (!mapped) return [];
+    return [{ locale: d.locale as Locale, url: `${mapped}/sitemap/${d.locale}.xml` }];
   });
 }
 
@@ -171,6 +307,8 @@ export type SiteRoutes = {
     locale: Locale,
     domains?: RouteLocaleDomain[],
     overrides?: PageSeoOverrides,
+    /** Origin serving the site, required in single-origin mode. */
+    origin?: string,
   ) => SitemapEntry[];
   sitemapIndexEntries: typeof sitemapIndexEntries;
 };
@@ -234,7 +372,12 @@ export function createSiteRoutes(PAGES: Record<string, PageDef>): SiteRoutes {
     const ogImage = seo.ogImage;
     const ogType = seo.ogType ?? "website";
     const twitterCard = seo.twitterCard ?? "summary_large_image";
-    const canonical = resolveAbsolute(pageKey, locale, origin, overrides);
+    const canonical = resolveAbsolute(
+      pageKey,
+      locale,
+      canonicalOrigin(locale, domains, origin),
+      overrides,
+    );
     const localesForPage = SUPPORTED_LOCALES.filter((l) => typeof page.slug[l] === "string");
 
     const meta: HeadMeta[] = [
@@ -251,9 +394,13 @@ export function createSiteRoutes(PAGES: Record<string, PageDef>): SiteRoutes {
     ];
 
     for (const alt of localesForPage) {
-      if (alt !== locale) {
-        meta.push({ property: "og:locale:alternate", content: alt });
-      }
+      if (alt === locale) continue;
+      // In explicit domain-mapping mode a language with no usable domain has
+      // no URL on this deployment, so naming it as an available translation
+      // points at nothing. Same rule as the hreflang links below, for the same
+      // reason: a missing alternate costs nothing, a wrong one costs the page.
+      if (domains.length > 0 && !originForLocale(alt, domains)) continue;
+      meta.push({ property: "og:locale:alternate", content: alt });
     }
 
     if (seo.keywords) {
@@ -273,21 +420,31 @@ export function createSiteRoutes(PAGES: Record<string, PageDef>): SiteRoutes {
       if (alt) meta.push({ name: "twitter:image:alt", content: alt });
     }
 
+    // Canonical stands whatever the alternates do: the locale being rendered is
+    // routable by definition, and dropping its canonical over a missing sibling
+    // domain would take the page's own SEO down with the alternate's.
     const links: HeadLink[] = [{ rel: "canonical", href: canonical }];
     for (const alt of localesForPage) {
-      const altOrigin = originForLocale(alt, domains) || origin;
+      const altOrigin = alternateOrigin(alt, domains, origin);
+      if (altOrigin === null) continue;
       links.push({
         rel: "alternate",
         hrefLang: alt,
         href: resolveAbsolute(pageKey, alt, altOrigin, overrides),
       });
     }
-    const defaultOrigin = originForLocale(DEFAULT_LOCALE, domains) || origin;
-    links.push({
-      rel: "alternate",
-      hrefLang: "x-default",
-      href: resolveAbsolute(pageKey, DEFAULT_LOCALE, defaultOrigin, overrides),
-    });
+    // x-default follows the deployment's own default — the flagged mapping in
+    // explicit mode, the site's default locale in single-origin mode. When
+    // there is no valid one, or the page does not publish it, the link is
+    // omitted rather than pointed at a fabricated origin.
+    const fallback = xDefaultTarget(domains, origin, localesForPage);
+    if (fallback) {
+      links.push({
+        rel: "alternate",
+        hrefLang: "x-default",
+        href: resolveAbsolute(pageKey, fallback.locale, fallback.origin, overrides),
+      });
+    }
 
     const scripts: HeadScript[] = [];
     if (seo.jsonLd) {
@@ -307,25 +464,36 @@ export function createSiteRoutes(PAGES: Record<string, PageDef>): SiteRoutes {
     locale: Locale,
     domains: RouteLocaleDomain[] = [],
     overrides?: PageSeoOverrides,
+    publicOriginValue: string = "",
   ): SitemapEntry[] {
-    const origin = originForLocale(locale, domains);
+    // In explicit domain-mapping mode a locale with no usable domain of its own
+    // has no sitemap: every URL in it would be an address this deployment does
+    // not serve. In single-origin mode the one hostname serves every language,
+    // so the caller's origin is what the URLs hang off — and without one there
+    // is nothing to emit, because a sitemap of relative paths is not a sitemap.
+    const origin =
+      domains.length > 0 ? originForLocale(locale, domains) : publicOrigin(publicOriginValue);
+    if (!origin) return [];
+
     const out: SitemapEntry[] = [];
     for (const key of Object.keys(PAGES) as PageKey[]) {
       const locales = publishedLocales(key, overrides);
       if (!locales.includes(locale)) continue;
-      const alternates: Array<{ locale: Locale | "x-default"; url: string }> = locales.map((l) => ({
-        locale: l,
-        url: resolveAbsolute(key, l, originForLocale(l, domains) || origin, overrides),
-      }));
-      alternates.push({
-        locale: "x-default",
-        url: resolveAbsolute(
-          key,
-          DEFAULT_LOCALE,
-          originForLocale(DEFAULT_LOCALE, domains) || origin,
-          overrides,
-        ),
-      });
+      const alternates: Array<{ locale: Locale | "x-default"; url: string }> = [];
+      for (const l of locales) {
+        const altOrigin = alternateOrigin(l, domains, origin);
+        if (altOrigin === null) continue;
+        alternates.push({ locale: l, url: resolveAbsolute(key, l, altOrigin, overrides) });
+      }
+      // Same rule as the page head, so a crawler cannot be told two different
+      // things about which URL is the fallback.
+      const fallback = xDefaultTarget(domains, origin, locales);
+      if (fallback) {
+        alternates.push({
+          locale: "x-default",
+          url: resolveAbsolute(key, fallback.locale, fallback.origin, overrides),
+        });
+      }
       out.push({
         pageKey: key,
         locale,

package/src/site/site-url.ts

@@ -7,29 +7,92 @@
  * Pure module — no database, no filesystem, no network. Safe to import from
  * tests, scripts and server code.
  */
+import { hostMatchKey, parseCanonicalDomain } from "./host";
 
-/** Strip scheme, path, trailing dots/slashes and a leading `www.`. */
+/** Strip scheme, path, trailing dots/slashes, a port and a leading `www.`. */
 export function normalizeHost(value: string): string {
-  return (value ?? "")
-    .trim()
-    .replace(/^[a-z][a-z0-9+.-]*:\/\//i, "")
-    .replace(/\/.*$/, "")
-    .replace(/\.+$/, "")
-    .replace(/^www\./i, "")
-    .toLowerCase();
+  return hostMatchKey(value);
 }
 
-/** The configured site origin (`https://host`), or null when unset. */
-export function siteOrigin(env: NodeJS.ProcessEnv = process.env): string | null {
-  const raw = (env["SITE_URL"] ?? "").trim().replace(/\/+$/, "");
+/** Highest port number a URL authority can carry. */
+const MAX_PORT = 65535;
+
+/** `SITE_URL` broken into the three parts every helper here needs. */
+type SiteUrlParts = { scheme: "http" | "https"; host: string; port: string };
+
+/**
+ * Read `SITE_URL` into a scheme, a canonical hostname and a port — or null.
+ *
+ * The raw value is validated *before* it is normalized, which is the whole
+ * point of this function. Prefixing `https://` onto anything that does not
+ * already look like a URL turns `ftp://example.com` into
+ * `https://ftp://example.com`, and normalizing that leaves the hostname `ftp`
+ * — a host nobody configured, invented from a value that should have been
+ * refused. Every helper below returns null rather than a guess, because a
+ * fabricated hostname reaches the backoffice redirect and the canonical URL.
+ *
+ * `parseCanonicalDomain` does the rejecting: it already knows about
+ * credentials, non-HTTP schemes with or without slashes, internal whitespace,
+ * unusable labels and non-numeric ports.
+ */
+function parseSiteUrl(env: NodeJS.ProcessEnv = process.env): SiteUrlParts | null {
+  const raw = (env["SITE_URL"] ?? "").trim();
   if (!raw) return null;
-  return /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+
+  const parsed = parseCanonicalDomain(raw);
+  if (!parsed.ok) return null;
+
+  // A bare hostname is allowed and means https. An explicit scheme is kept,
+  // and anything other than http/https was already refused above.
+  const explicit = /^(https?):\/\//i.exec(raw);
+  const scheme = (explicit ? (explicit[1] as string).toLowerCase() : "https") as "http" | "https";
+
+  const authority = raw.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "").replace(/[/?#].*$/, "");
+  const port = /:(\d{1,5})$/.exec(authority)?.[1] ?? "";
+  if (port && (Number(port) === 0 || Number(port) > MAX_PORT)) return null;
+
+  return { scheme, host: parsed.domain, port };
 }
 
-/** The hostname of SITE_URL, normalized, or null when SITE_URL is unset. */
+/**
+ * The configured site origin, or null when `SITE_URL` is unset or unusable.
+ *
+ * An origin is scheme, host and port — never a path. A trailing path left on
+ * the end reappears in every link built by concatenation, so
+ * `https://voyara.se/path/` would yield `https://voyara.se/path/om-oss`.
+ */
+export function siteOrigin(env: NodeJS.ProcessEnv = process.env): string | null {
+  const parts = parseSiteUrl(env);
+  if (!parts) return null;
+  return `${parts.scheme}://${parts.host}${parts.port ? `:${parts.port}` : ""}`;
+}
+
+/**
+ * The hostname of SITE_URL as a *match key*, or null when it is unset or
+ * unusable.
+ *
+ * A leading `www.` is folded away, which is what comparing an incoming request
+ * host against the configured one wants. It is not what stating a hostname
+ * wants — see `siteCanonicalHost`.
+ */
 export function siteHost(env: NodeJS.ProcessEnv = process.env): string | null {
-  const origin = siteOrigin(env);
-  if (!origin) return null;
-  const host = normalizeHost(origin);
-  return host || null;
+  const parts = parseSiteUrl(env);
+  if (!parts) return null;
+  return hostMatchKey(parts.host) || null;
+}
+
+/**
+ * The hostname of SITE_URL in its canonical form, or null when SITE_URL is
+ * unset or unusable. A configured `www.` is preserved.
+ *
+ * Matching and canonical output are different jobs, so they get different
+ * functions. `siteHost` answers "is this request on the configured host?", and
+ * folding `www.` away is correct there. Anything that *states* the hostname —
+ * the effective admin host, and the redirect built from it — must use this
+ * one: a deployment whose SITE_URL is `https://www.voyara.se` is served from
+ * `www.voyara.se`, and sending the backoffice to an apex it never configured
+ * is a redirect to a hostname that may not answer at all.
+ */
+export function siteCanonicalHost(env: NodeJS.ProcessEnv = process.env): string | null {
+  return parseSiteUrl(env)?.host ?? null;
 }

package/src/tracking/injections.ts

@@ -6,6 +6,24 @@
  * into three final HTML strings that the root shell renders.
  */
 
+import { hostMatchKey, hostsMatch, isValidCanonicalDomain } from "../site/host";
+
+/**
+ * Raised when an insert cannot be identified, and shown to the administrator
+ * verbatim.
+ *
+ * It lives in this module rather than beside the server function that raises
+ * it because the screen has to recognise it too, and a browser-facing route
+ * importing a server core to read one string pulls that whole module into the
+ * client graph. Both sides import it from here.
+ *
+ * The wording asks for a reload rather than a retry on purpose: the row may
+ * already be there, so sending it again is the one action that could duplicate
+ * it.
+ */
+export const MISSING_CREATED_ID =
+  "The server did not return the new profile ID. Reload before trying again.";
+
 export type InjectionScopeType = "global" | "locale" | "domain";
 
 export type ExtraMeta = { name: string; content: string };
@@ -36,18 +54,30 @@ export type InjectionBundle = {
 
 export const EMPTY_BUNDLE: InjectionBundle = { head: "", bodyStart: "", bodyEnd: "" };
 
-/** Escapes a value used inside a generated snippet / attribute. */
+/** Escapes a value used inside a generated snippet. IDs are identifiers. */
 function esc(v: string): string {
   return v.replace(/[\\'"<>]/g, "");
 }
 
+/** Escapes a value placed inside a double-quoted HTML attribute. */
+function attr(v: string): string {
+  return v
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * The key a request host is matched on.
+ *
+ * Delegates to the platform's single hostname implementation, so a
+ * domain-scoped profile matches exactly what the Languages & domains system
+ * would match — apex and one leading `www.` included, casing and ports
+ * handled the same way.
+ */
 export function normalizeHostname(host: string): string {
-  return host
-    .replace(/^https?:\/\//, "")
-    .replace(/\/+$/, "")
-    .replace(/:\d+$/, "")
-    .replace(/^www\./, "")
-    .toLowerCase();
+  return hostMatchKey(host);
 }
 
 /* ---------------- Snippet builders ---------------- */
@@ -82,10 +112,17 @@ export function tiktokPixelHead(id: string): string {
   return `<script>!function(w,d,t){w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie"];ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e};ttq.load=function(e,n){var r="https://analytics.tiktok.com/i18n/pixel/events.js";ttq._i=ttq._i||{};ttq._i[e]=[];ttq._i[e]._u=r;ttq._t=ttq._t||{};ttq._t[e]=+new Date;ttq._o=ttq._o||{};ttq._o[e]=n||{};var o=d.createElement("script");o.type="text/javascript";o.async=!0;o.src=r+"?sdkid="+e+"&lib="+t;var a=d.getElementsByTagName("script")[0];a.parentNode.insertBefore(o,a)};ttq.load('${p}');ttq.page();}(window,document,'ttq');</script>`;
 }
 
+/**
+ * Verification meta tags.
+ *
+ * Both halves are escaped as HTML attribute values: this field is meta-only.
+ * Raw markup belongs in the head / body-start / body-end code fields, which
+ * are deliberately passed through untouched.
+ */
 export function extraMetaTags(items: ExtraMeta[]): string {
   return items
     .filter((m) => m.name && m.content)
-    .map((m) => `<meta name="${esc(m.name)}" content="${m.content.replace(/"/g, "&quot;")}" />`)
+    .map((m) => `<meta name="${attr(m.name)}" content="${attr(m.content)}" />`)
     .join("");
 }
 
@@ -136,7 +173,13 @@ export function selectProfiles(
     .filter((p) => {
       if (p.scope_type === "global") return true;
       if (p.scope_type === "locale") return p.scope_value === locale;
-      return normalizeHostname(p.scope_value) === h;
+      /*
+       * Validated, not just normalized. Normalizing strips the scheme, so
+       * `ftp://example.com` compared afterwards is the perfectly ordinary
+       * `example.com` — and a profile nobody could have saved through the
+       * backoffice would start firing on a host it never named.
+       */
+      return isValidCanonicalDomain(p.scope_value) && hostsMatch(p.scope_value, h);
     })
     .sort((a, b) => rank[a.scope_type] - rank[b.scope_type] || a.sort_order - b.sort_order);
 }

package/src/types/css-modules.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Side-effect stylesheet imports (the popup package's admin.css). The bundler
+ * that consumes this source understands them natively; this declaration only
+ * teaches the package's own typechecker that they exist.
+ */
+declare module "*.css";

package/src/ui/Reveal.tsx

@@ -1,25 +1,87 @@
-import { useEffect, useRef, useState, type ReactNode } from "react";
+import { useEffect, useLayoutEffect, useRef, useState, type ReactNode } from "react";
 
+/**
+ * How a block appears when the reader reaches it.
+ *
+ *  - `immediate` — present and visible, with no entrance animation.
+ *  - `fade`      — fades and rises gently the first time it enters the viewport.
+ */
+export type RevealMode = "immediate" | "fade";
+
+export const REVEAL_MODES: readonly RevealMode[] = ["immediate", "fade"];
+
+/**
+ * Blocks saved before the setting existed always faded in, so that is what a
+ * block without one keeps doing. Changing this would restyle every page that
+ * is already published.
+ */
+export const DEFAULT_REVEAL_MODE: RevealMode = "fade";
+
+/** Read a stored value that may predate the setting, or be anything at all. */
+export function normalizeRevealMode(value: unknown): RevealMode {
+  return value === "immediate" || value === "fade" ? value : DEFAULT_REVEAL_MODE;
+}
+
+function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  );
+}
+
+// Hiding has to happen before the browser paints, or the reader sees the
+// content flash in and back out. On the server there is nothing to lay out.
+const useBeforePaint = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+const MOTION = "transition-all duration-[900ms] ease-out will-change-transform";
+
+/**
+ * Fade a block in the first time it is scrolled into view.
+ *
+ * The content is *rendered visible* and only then hidden, by a layout effect,
+ * for the animation. That order matters: the server's HTML, a crawler's copy
+ * and a reader whose script never arrived all get the text plainly visible,
+ * and nothing worth reading is behind an IntersectionObserver. Readers who
+ * asked for reduced motion are never hidden at all.
+ */
 export function Reveal({
   children,
   delay = 0,
   className = "",
+  mode = DEFAULT_REVEAL_MODE,
 }: {
   children: ReactNode;
   delay?: number;
   className?: string;
+  /** `immediate` skips the animation entirely. */
+  mode?: RevealMode;
 }) {
   const ref = useRef<HTMLDivElement>(null);
-  const [shown, setShown] = useState(false);
+  const [state, setState] = useState<"visible" | "armed" | "revealed">("visible");
 
-  useEffect(() => {
+  useBeforePaint(() => {
+    // A live preview can change an already-mounted block from Fade to
+    // Immediate while it is still below the viewport. Clear the armed state
+    // before taking any non-animation path, or the old opacity-0 classes would
+    // remain after its observer has been disconnected.
+    if (
+      mode !== "fade" ||
+      prefersReducedMotion() ||
+      typeof IntersectionObserver === "undefined"
+    ) {
+      setState("visible");
+      return;
+    }
     const el = ref.current;
     if (!el) return;
+
+    setState("armed");
     const io = new IntersectionObserver(
       (entries) => {
         for (const e of entries) {
           if (e.isIntersecting) {
-            setShown(true);
+            setState("revealed");
             io.disconnect();
             break;
           }
@@ -29,17 +91,20 @@ export function Reveal({
     );
     io.observe(el);
     return () => io.disconnect();
-  }, []);
+  }, [mode]);
 
   return (
     <div
       ref={ref}
-      style={{ transitionDelay: `${delay}ms` }}
+      style={state === "visible" ? undefined : { transitionDelay: `${delay}ms` }}
       className={[
-        "transition-all duration-[900ms] ease-out will-change-transform",
-        shown ? "opacity-100 translate-y-0" : "opacity-0 translate-y-6",
+        state === "visible" ? "" : MOTION,
+        state === "armed" ? "opacity-0 translate-y-6" : "",
+        state === "revealed" ? "opacity-100 translate-y-0" : "",
         className,
-      ].join(" ")}
+      ]
+        .filter(Boolean)
+        .join(" ")}
     >
       {children}
     </div>