@tribe-nest/forge 3.24.0 → 3.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.24.0",
+  "version": "3.25.0",
   "publishConfig": {
     "access": "public"
   },
@@ -39,6 +39,7 @@
   },
   "devDependencies": {
     "@types/react": "^19.1.2",
+    "simple-icons": "^16.28.0",
     "typescript": "~5.8.3"
   },
   "license": "ISC"

package/src/types/models.ts

@@ -1893,6 +1893,11 @@ export interface IMusicLinkDestination {
 
 /** Per-link presentation, layered over the site theme by `MusicLinkPage`. */
 export interface IMusicLinkTheme {
+  /**
+   * Which of the five layouts to render. Composition, not colour: the tokens
+   * below tune whichever one is chosen.
+   */
+  style?: "classic" | "immersive" | "split" | "minimal" | "compact";
   mode?: "light" | "dark";
   background?: string;
   text?: string;
@@ -1911,6 +1916,8 @@ export interface IMusicLink {
   artistName: string | null;
   description: string | null;
   artworkUrl: string | null;
+  /** 30-second preview, played over the artwork. Apple's, which does not expire. */
+  previewUrl: string | null;
   releaseDate: string | null;
   theme: IMusicLinkTheme | null;
   destinations: IMusicLinkDestination[];

package/src/ui/styled/MusicLinkPage.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import type { CSSProperties } from "react";
 import type { IMusicLink } from "../../types/models";
 import { useMusicLink } from "../../data/queries/useMusicLink";
@@ -7,6 +7,8 @@ import { usePageMetaPixel } from "../analytics/PageMetaPixel";
 import { PageMetaPixel } from "../analytics/PageMetaPixel";
 import { useThemeTokens } from "../theme/ForgeThemeProvider";
 import { PageActions } from "./PageActions";
+import { DEFAULT_MUSIC_LINK_STYLE, MusicLinkLayout, type LayoutParts, type MusicLinkStyle } from "./musicLinkStyles";
+import { useCookieConsent } from "../headless/consent/useCookieConsent";
 
 /**
  * How each streaming service is presented.
@@ -14,13 +16,15 @@ import { PageActions } from "./PageActions";
  * `color` is the service's own brand colour, used for the badge, and `label` is
  * the name a fan recognises rather than the API key.
  *
- * There is deliberately no logo artwork here. Reproducing a dozen trademarked
- * marks from memory gets some of them subtly wrong, and every one of these
- * services publishes brand guidelines with rules about colour, clear space and
- * permitted alterations. A wrong Spotify logo on an artist's own domain is the
- * artist's problem, not ours to create. Drop real SVGs in behind `icon` when
- * the assets have been taken from each service's brand kit; the layout already
- * reserves the space.
+ * Marks and brand hex come from `musicServiceIcons.ts`, generated from
+ * simple-icons rather than drawn by hand: reproducing a dozen trademarked logos
+ * from memory gets several subtly wrong, and a wrong Spotify mark on an artist's
+ * own domain is the artist's problem. Four services (Amazon Music, Boomplay,
+ * Anghami, Audius) have no entry there and keep the initial badge; adding them
+ * means finding an officially published SVG, not guessing one.
+ *
+ * `color` below is only the fallback for those four. Anything with a real icon
+ * uses the official hex from the generated file.
  */
 const SERVICES: Record<string, { label: string; color: string; action?: string }> = {
   spotify: { label: "Spotify", color: "#1DB954", action: "Play" },
@@ -42,6 +46,20 @@ const SERVICES: Record<string, { label: string; color: string; action?: string }
   tiktok: { label: "TikTok", color: "#000000", action: "Open" },
 };
 
+/**
+ * Below `CookieConsent`, which is fixed at 70.
+ *
+ * This page covers the viewport, so anything the shell renders underneath is
+ * hidden. The consent banner must NOT be: this page fires a Meta Pixel, so
+ * hiding the control that governs it would mean running marketing tracking
+ * with the consent UI painted over. The gap is deliberate, and a spec asserts
+ * the ordering so a future bump here cannot quietly close it.
+ */
+const OVERLAY_Z_INDEX = 60;
+
+/** TribeNest's hosted policy, matching what `CookieConsent` falls back to. */
+const TRIBENEST_PRIVACY_URL = "https://www.tribenest.co/privacy";
+
 const serviceMeta = (platform: string) => SERVICES[platform] ?? { label: platform, color: "#666666", action: "Open" };
 
 export interface MusicLinkPageProps {
@@ -51,6 +69,13 @@ export interface MusicLinkPageProps {
   initialLink?: IMusicLink | null;
   /** Heading above the service list. */
   listHeading?: string;
+  /** The site's own privacy policy. Falls back to TribeNest's hosted one. */
+  privacyHref?: string;
+  /** The "Powered by TribeNest" credit. */
+  showPoweredBy?: boolean;
+  /** Accessible names for the preview control. */
+  playLabel?: string;
+  pauseLabel?: string;
   /** Shown when the slug resolves to nothing. */
   notFoundMessage?: string;
   className?: string;
@@ -86,6 +111,10 @@ export function MusicLinkPage({
   slug,
   initialLink,
   listHeading = "Listen on",
+  privacyHref,
+  showPoweredBy = true,
+  playLabel = "Play a preview",
+  pauseLabel = "Pause the preview",
   notFoundMessage = "This link is no longer available.",
   className,
   style,
@@ -127,9 +156,14 @@ export function MusicLinkPage({
     };
   }, [siteTokens, link?.theme]);
 
+  // Falls back rather than throwing on an unknown value: a style saved by a
+  // newer admin than the site's Forge must render as something, and Classic is
+  // the safe something.
+  const activeStyle: MusicLinkStyle = (link?.theme?.style as MusicLinkStyle) ?? DEFAULT_MUSIC_LINK_STYLE;
+
   const pixelId = link?.metaPixelId ?? "";
   const { fire } = usePageMetaPixel(pixelId);
-  const { trackBeacon } = useTrackEvent();
+  const { track, trackBeacon } = useTrackEvent();
 
   // Lock the page behind the overlay. Without this the tenant's own page keeps
   // scrolling underneath on iOS, which reads as a rendering bug.
@@ -142,6 +176,41 @@ export function MusicLinkPage({
     };
   }, []);
 
+  const audioRef = useRef<HTMLAudioElement | null>(null);
+  const [playing, setPlaying] = useState(false);
+
+  // Stop the preview when the page goes away. Without this a fan who taps play
+  // and then taps Spotify leaves audio running underneath the store they just
+  // opened, which on mobile is both confusing and hard to stop.
+  useEffect(() => {
+    return () => {
+      audioRef.current?.pause();
+    };
+  }, []);
+
+  const togglePreview = () => {
+    const audio = audioRef.current;
+    if (!audio) return;
+    if (audio.paused) {
+      // A tap IS the user gesture mobile autoplay policy requires, so this is
+      // allowed where an autoplaying preview would be blocked. `catch` because
+      // it still rejects on some in-app browsers and a rejected promise here
+      // must not surface as an error to a fan.
+      void audio
+        .play()
+        .then(() => setPlaying(true))
+        .catch(() => setPlaying(false));
+    } else {
+      audio.pause();
+      setPlaying(false);
+    }
+    if (!audio.paused)
+      track("preview_play", {
+        pathname: typeof window !== "undefined" ? window.location.pathname : undefined,
+        slug: link?.slug,
+      });
+  };
+
   const destinations = useMemo(() => link?.destinations ?? [], [link]);
 
   const onDestinationClick = (platform: string, url: string) => {
@@ -170,146 +239,201 @@ export function MusicLinkPage({
     );
   }
 
+  const previewButton = (size: number) =>
+    link.previewUrl ? (
+      <button
+        type="button"
+        onClick={togglePreview}
+        aria-label={playing ? pauseLabel : playLabel}
+        data-track-skip=""
+        style={{
+          width: size,
+          height: size,
+          borderRadius: 999,
+          border: "none",
+          cursor: "pointer",
+          background: "rgba(0,0,0,0.55)",
+          backdropFilter: "blur(4px)",
+          color: "#ffffff",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          padding: 0,
+          flex: "none",
+        }}
+      >
+        <svg
+          viewBox="0 0 24 24"
+          width={Math.round(size * 0.44)}
+          height={Math.round(size * 0.44)}
+          fill="currentColor"
+          aria-hidden="true"
+        >
+          {playing ? (
+            <path d="M6 5h4v14H6zM14 5h4v14h-4z" />
+          ) : (
+            <path d="M8 5.14v13.72a.5.5 0 0 0 .76.43l11.14-6.86a.5.5 0 0 0 0-.86L8.76 4.71a.5.5 0 0 0-.76.43z" />
+          )}
+        </svg>
+      </button>
+    ) : null;
+
+  const artwork = (size: number) =>
+    link.artworkUrl ? (
+      <div style={{ position: "relative", lineHeight: 0 }}>
+        <img
+          src={link.artworkUrl}
+          alt={link.title}
+          width={size}
+          height={size}
+          style={{
+            width: size,
+            height: size,
+            maxWidth: "70vw",
+            maxHeight: "70vw",
+            objectFit: "cover",
+            borderRadius: t.cornerRadius,
+            boxShadow: "0 18px 50px rgba(0,0,0,0.45)",
+          }}
+        />
+
+        {/*
+          The preview, over the cover. Only when there IS one: a play button that
+          does nothing is worse than no play button, and plenty of releases
+          resolve without a preview. Scaled with the artwork so it stays
+          proportionate on the styles that shrink the cover.
+        */}
+        {size >= 110 ? (
+          <div
+            style={{ position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center" }}
+          >
+            {previewButton(Math.round(size * 0.25))}
+          </div>
+        ) : null}
+      </div>
+    ) : null;
+
+  const parts: LayoutParts = {
+    t,
+    link: {
+      title: link.title,
+      artistName: link.artistName,
+      description: link.description,
+      artworkUrl: link.artworkUrl,
+    },
+    destinations,
+    metaFor: serviceMeta,
+    onDestinationClick,
+    artwork,
+    previewButton: previewButton(72),
+    listHeading,
+    pageActions: (
+      <div style={{ width: "100%", marginTop: 28 }}>
+        <PageActions pageType="music_link" entityId={link.id} />
+      </div>
+    ),
+    footer: <SmartLinkFooter t={t} privacyHref={privacyHref} showPoweredBy={showPoweredBy} />,
+  };
+
+  // The immersive style uses the cover AS the page, so its backdrop is opaque
+  // rather than the faint blur the others sit on.
+  const immersive = activeStyle === "immersive";
+
   return (
     <Overlay
       t={t}
       className={className}
       style={style}
       artworkUrl={link.theme?.artworkBackdrop === false ? null : link.artworkUrl}
+      backdropOpacity={immersive ? 0.62 : 0.35}
+      scrim={immersive}
     >
       {pixelId ? <PageMetaPixel pixelId={pixelId} /> : null}
 
-      <div style={{ width: "100%", maxWidth: 420, display: "flex", flexDirection: "column", alignItems: "center" }}>
-        {link.artworkUrl ? (
-          <img
-            src={link.artworkUrl}
-            alt={link.title}
-            width={260}
-            height={260}
-            style={{
-              width: 260,
-              height: 260,
-              maxWidth: "70vw",
-              maxHeight: "70vw",
-              objectFit: "cover",
-              borderRadius: t.cornerRadius,
-              boxShadow: "0 18px 50px rgba(0,0,0,0.45)",
-            }}
-          />
-        ) : null}
+      {link.previewUrl ? (
+        <audio
+          ref={audioRef}
+          src={link.previewUrl}
+          preload="none"
+          onEnded={() => setPlaying(false)}
+          onPause={() => setPlaying(false)}
+        />
+      ) : null}
 
-        <h1
-          style={{
-            margin: "24px 0 4px",
-            fontSize: 24,
-            lineHeight: 1.25,
-            textAlign: "center",
-            color: t.text,
-            fontFamily: t.headingFontFamily || t.fontFamily,
-          }}
-        >
-          {link.title}
-        </h1>
+      <MusicLinkLayout style={activeStyle} parts={parts} />
+    </Overlay>
+  );
+}
 
-        {link.artistName ? (
-          <p style={{ margin: 0, fontSize: 16, color: t.muted, fontFamily: t.fontFamily }}>{link.artistName}</p>
-        ) : null}
+function SmartLinkFooter({
+  t,
+  privacyHref,
+  showPoweredBy,
+}: {
+  t: ReturnType<typeof useThemeTokens>;
+  privacyHref?: string;
+  showPoweredBy: boolean;
+}) {
+  const { reopen } = useCookieConsent();
+  const href = privacyHref ?? TRIBENEST_PRIVACY_URL;
+  const external = !privacyHref;
 
-        {link.description ? (
-          <p
-            style={{
-              margin: "12px 0 0",
-              fontSize: 14,
-              textAlign: "center",
-              color: t.muted,
-              fontFamily: t.fontFamily,
-            }}
-          >
-            {link.description}
-          </p>
-        ) : null}
+  const linkStyle: CSSProperties = {
+    color: t.muted,
+    textDecoration: "none",
+    borderBottom: `1px solid ${t.border}`,
+    background: "none",
+    border: "none",
+    borderBottomWidth: 1,
+    borderBottomStyle: "solid",
+    borderBottomColor: t.border,
+    padding: 0,
+    font: "inherit",
+    cursor: "pointer",
+  };
 
-        {destinations.length > 0 ? (
-          <p
-            style={{
-              margin: "28px 0 12px",
-              fontSize: 12,
-              letterSpacing: "0.08em",
-              textTransform: "uppercase",
-              color: t.muted,
-              fontFamily: t.fontFamily,
-            }}
-          >
-            {listHeading}
-          </p>
-        ) : null}
+  return (
+    <footer
+      style={{
+        marginTop: 36,
+        display: "flex",
+        flexWrap: "wrap",
+        alignItems: "center",
+        justifyContent: "center",
+        gap: 14,
+        fontSize: 12,
+        color: t.muted,
+        fontFamily: t.fontFamily,
+      }}
+    >
+      <a
+        href={href}
+        {...(external ? { target: "_blank", rel: "noopener noreferrer" } : {})}
+        data-track-skip=""
+        style={linkStyle}
+      >
+        Privacy
+      </a>
 
-        <div style={{ width: "100%", display: "flex", flexDirection: "column", gap: 10 }}>
-          {destinations.map((destination) => {
-            const meta = serviceMeta(destination.platform);
-            return (
-              <a
-                key={destination.platform}
-                href={destination.url}
-                target="_blank"
-                rel="noopener noreferrer"
-                // Stands the global click listener down. It would otherwise
-                // record a second, poorer event for this same tap, and its
-                // payload would drive a duplicate CAPI Lead.
-                data-track-skip=""
-                data-track={`music-link-${destination.platform}`}
-                onClick={() => onDestinationClick(destination.platform, destination.url)}
-                style={{
-                  display: "flex",
-                  alignItems: "center",
-                  gap: 12,
-                  padding: "12px 14px",
-                  borderRadius: t.cornerRadius,
-                  background: t.surface,
-                  border: `1px solid ${t.border}`,
-                  color: t.text,
-                  textDecoration: "none",
-                  fontFamily: t.fontFamily,
-                }}
-              >
-                <span
-                  aria-hidden="true"
-                  style={{
-                    width: 34,
-                    height: 34,
-                    flex: "0 0 34px",
-                    borderRadius: 999,
-                    background: meta.color,
-                    color: "#ffffff",
-                    display: "flex",
-                    alignItems: "center",
-                    justifyContent: "center",
-                    fontSize: 15,
-                    fontWeight: 700,
-                  }}
-                >
-                  {meta.label.charAt(0)}
-                </span>
-                <span style={{ flex: 1, fontSize: 15, fontWeight: 600 }}>{meta.label}</span>
-                <span style={{ fontSize: 13, fontWeight: 700, color: t.primary }}>{meta.action}</span>
-              </a>
-            );
-          })}
-        </div>
+      {/* Reopening the banner is the only way a visitor can change their mind
+          once a choice is stored, and the shell puts this in the footer we are
+          covering. */}
+      <button type="button" onClick={reopen} data-track-skip="" style={linkStyle}>
+        Cookie settings
+      </button>
 
-        {/*
-          The creator's own additions: a newsletter form, a vinyl pre-order, a
-          lead magnet, a donation. This route is a platform-owned chassis file
-          that is re-materialized from the starter on every build, so anything
-          added to it IN CODE would be overwritten on the next deploy. Page
-          actions are data instead, resolved per link with a per-page-type
-          default, so the shell stays ours and the contents stay theirs.
-        */}
-        <div style={{ width: "100%", marginTop: 28 }}>
-          <PageActions pageType="music_link" entityId={link.id} />
-        </div>
-      </div>
-    </Overlay>
+      {showPoweredBy ? (
+        <a
+          href="https://www.tribenest.co"
+          target="_blank"
+          rel="noopener noreferrer"
+          data-track-skip=""
+          style={{ ...linkStyle, borderBottom: "none" }}
+        >
+          Powered by TribeNest
+        </a>
+      ) : null}
+    </footer>
   );
 }
 
@@ -319,12 +443,18 @@ function Overlay({
   className,
   style,
   children,
+  backdropOpacity = 0.35,
+  scrim = false,
 }: {
   t: ReturnType<typeof useThemeTokens>;
   artworkUrl?: string | null;
   className?: string;
   style?: CSSProperties;
   children: React.ReactNode;
+  /** How strongly the cover shows through. Immersive leans on it; the rest hint. */
+  backdropOpacity?: number;
+  /** A dark gradient over the cover, so light type stays legible on any artwork. */
+  scrim?: boolean;
 }) {
   return (
     <div
@@ -332,7 +462,7 @@ function Overlay({
       style={{
         position: "fixed",
         inset: 0,
-        zIndex: 60,
+        zIndex: OVERLAY_Z_INDEX,
         overflowY: "auto",
         background: t.background,
         display: "flex",
@@ -354,12 +484,35 @@ function Overlay({
             backgroundPosition: "center",
             filter: "blur(48px) saturate(1.4)",
             transform: "scale(1.2)",
-            opacity: 0.35,
+            opacity: backdropOpacity,
+            pointerEvents: "none",
+          }}
+        />
+      ) : null}
+      {/* Artwork is uncontrollable input: a pale cover would leave white type on
+          white. The scrim guarantees a dark ground under the immersive style. */}
+      {artworkUrl && scrim ? (
+        <div
+          aria-hidden="true"
+          style={{
+            position: "absolute",
+            inset: 0,
+            background: "linear-gradient(180deg, rgba(0,0,0,0.35) 0%, rgba(0,0,0,0.78) 65%, rgba(0,0,0,0.9) 100%)",
             pointerEvents: "none",
           }}
         />
       ) : null}
-      <div style={{ position: "relative", width: "100%", display: "flex", justifyContent: "center" }}>{children}</div>
+      <div
+        style={{
+          position: "relative",
+          width: "100%",
+          display: "flex",
+          justifyContent: "center",
+          minHeight: scrim ? "100%" : undefined,
+        }}
+      >
+        {children}
+      </div>
     </div>
   );
 }

package/src/ui/styled/_tests/musicLinkChrome.spec.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const read = (p: string) => readFileSync(join(__dirname, "..", p), "utf8");
+
+/**
+ * `MusicLinkPage` covers the viewport, so everything the app shell renders
+ * underneath it is hidden. These assertions pin the two things that must NOT be.
+ *
+ * Source assertions rather than a render test on purpose: what is being checked
+ * is a relationship between two components' stacking, which a render of either
+ * one alone cannot see, and which a person editing one of them would have no
+ * reason to think about.
+ */
+describe("music link page chrome", () => {
+  const page = read("MusicLinkPage.tsx");
+  const consent = read("CookieConsent.tsx");
+
+  const zIndexOf = (src: string, pattern: RegExp) => {
+    const match = pattern.exec(src);
+    if (!match) throw new Error("no z-index found");
+    return Number(match[1]);
+  };
+
+  it("stays below the cookie banner", () => {
+    // The page fires a Meta Pixel. Painting over the consent UI would mean
+    // running marketing tracking with its only control hidden, which is a
+    // compliance problem rather than a layout one.
+    const overlay = zIndexOf(page, /const OVERLAY_Z_INDEX = (\d+);/);
+    const banner = zIndexOf(consent, /zIndex:\s*(\d+)/);
+
+    expect(overlay).toBeLessThan(banner);
+  });
+
+  it("carries its own privacy and cookie-settings links", () => {
+    // The site footer that normally holds these is covered by the overlay, so
+    // the page has to supply them itself or a visitor has no way to read the
+    // policy or withdraw consent from the page that tracks them.
+    expect(page).toContain("Cookie settings");
+    expect(page).toContain("Privacy");
+    expect(page).toContain("useCookieConsent");
+  });
+
+  it("credits the platform", () => {
+    expect(page).toContain("Powered by TribeNest");
+  });
+});

package/src/ui/styled/musicLinkStyles.tsx

@@ -0,0 +1,475 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { IMusicLinkDestination } from "../../types/models";
+import { MUSIC_SERVICE_ICONS } from "./musicServiceIcons";
+import { readableBrandColor } from "../../utils/contrast";
+import type { useThemeTokens } from "../theme/ForgeThemeProvider";
+
+export type MusicLinkStyle = "classic" | "immersive" | "split" | "minimal" | "compact";
+
+export const MUSIC_LINK_STYLES: MusicLinkStyle[] = ["classic", "immersive", "split", "minimal", "compact"];
+
+export const DEFAULT_MUSIC_LINK_STYLE: MusicLinkStyle = "classic";
+
+/**
+ * The five presentations a release page can take.
+ *
+ * These are LAYOUTS, not palettes. Colour is already tunable per link through
+ * the theme tokens, and swapping colours never stops two releases looking like
+ * the same page. What makes an artist's link feel like theirs is composition:
+ * where the cover sits, how big the title is, whether the services read as a
+ * list or as a row of marks.
+ *
+ * Kept to five deliberately. Every one has to be maintained against both themes,
+ * both contrast fallbacks, the preview button, page actions and the footer, so a
+ * sixth is a real cost rather than another entry in a config file.
+ */
+export const MUSIC_LINK_STYLE_META: Record<MusicLinkStyle, { label: string; description: string }> = {
+  classic: {
+    label: "Classic",
+    description: "Centred cover, then one clearly labelled row per service. The safest choice and the default.",
+  },
+  immersive: {
+    label: "Immersive",
+    description: "The cover fills the screen behind frosted buttons. Best with strong, high-contrast artwork.",
+  },
+  split: {
+    label: "Split",
+    description: "Cover on one side, everything else on the other. Widescreen and editorial; stacks on a phone.",
+  },
+  minimal: {
+    label: "Minimal",
+    description: "The title is the artwork. A small thumbnail and services as plain marks, nothing else.",
+  },
+  compact: {
+    label: "Compact",
+    description: "A round cover over brand-coloured buttons. Reads fastest, and closest to a link-in-bio.",
+  },
+};
+
+export type ThemeTokens = ReturnType<typeof useThemeTokens>;
+
+export type ServiceMeta = { label: string; color: string; action?: string };
+
+export type LayoutParts = {
+  t: ThemeTokens;
+  link: {
+    title: string;
+    artistName: string | null;
+    description: string | null;
+    artworkUrl: string | null;
+  };
+  destinations: IMusicLinkDestination[];
+  metaFor: (platform: string) => ServiceMeta;
+  onDestinationClick: (platform: string, url: string) => void;
+  /** The cover plus its preview button, already assembled. */
+  artwork: (size: number) => ReactNode;
+  /**
+   * The preview control on its own, for layouts that do not show a cover to put
+   * it on. Immersive is the case: the artwork IS the page, so a second copy of
+   * it in the middle would be the thing that made it look like Classic with a
+   * wallpaper.
+   */
+  previewButton: ReactNode;
+  footer: ReactNode;
+  pageActions: ReactNode;
+  listHeading: string;
+};
+
+/* ────────────────────────────── shared pieces ────────────────────────────── */
+
+/**
+ * A service's mark, filled with the brand hex only where that survives the
+ * surface it sits on. Tidal and TikTok are pure black and vanish on a dark
+ * ground, so an unconditional brand fill ships an invisible logo.
+ */
+export function ServiceMark({
+  platform,
+  meta,
+  surface,
+  text,
+  size = 26,
+}: {
+  platform: string;
+  meta: ServiceMeta;
+  surface: string;
+  text: string;
+  size?: number;
+}) {
+  const icon = MUSIC_SERVICE_ICONS[platform];
+  const box: CSSProperties = {
+    width: size + 8,
+    height: size + 8,
+    flex: `0 0 ${size + 8}px`,
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+  };
+
+  if (icon) {
+    return (
+      <span aria-hidden="true" style={box}>
+        <svg
+          viewBox="0 0 24 24"
+          width={size}
+          height={size}
+          fill={readableBrandColor(icon.hex, surface, text)}
+          role="presentation"
+        >
+          <path d={icon.path} />
+        </svg>
+      </span>
+    );
+  }
+
+  return (
+    <span
+      aria-hidden="true"
+      style={{
+        ...box,
+        borderRadius: 999,
+        background: meta.color,
+        color: "#ffffff",
+        fontSize: size * 0.58,
+        fontWeight: 700,
+      }}
+    >
+      {meta.label.charAt(0)}
+    </span>
+  );
+}
+
+const anchorProps = (platform: string, url: string, onClick: LayoutParts["onDestinationClick"]) => ({
+  href: url,
+  target: "_blank" as const,
+  rel: "noopener noreferrer",
+  // Stands the global click listener down: this element reports its own event
+  // with a shared id, and a second, poorer event would double-count the tap.
+  "data-track-skip": "",
+  "data-track": `music-link-${platform}`,
+  onClick: () => onClick(platform, url),
+});
+
+/** Mark, name, action word. The most legible arrangement, and the default. */
+function ServiceRows({ parts, surface }: { parts: LayoutParts; surface: string }) {
+  const { t, destinations, metaFor, onDestinationClick } = parts;
+  return (
+    <div className="tn-ml-rows" style={{ width: "100%", display: "flex", flexDirection: "column", gap: 10 }}>
+      {destinations.map((d) => {
+        const meta = metaFor(d.platform);
+        return (
+          <a
+            key={d.platform}
+            {...anchorProps(d.platform, d.url, onDestinationClick)}
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: 12,
+              padding: "12px 14px",
+              borderRadius: t.cornerRadius,
+              background: surface,
+              border: `1px solid ${t.border}`,
+              color: t.text,
+              textDecoration: "none",
+              fontFamily: t.fontFamily,
+            }}
+          >
+            <ServiceMark platform={d.platform} meta={meta} surface={surface} text={t.text} />
+            <span style={{ flex: 1, fontSize: 15, fontWeight: 600 }}>{meta.label}</span>
+            <span style={{ fontSize: 13, fontWeight: 700, color: t.primary }}>{meta.action}</span>
+          </a>
+        );
+      })}
+    </div>
+  );
+}
+
+/** Icon-only marks in a wrapped row. No labels: the logos ARE the labels. */
+function ServiceMarks({ parts }: { parts: LayoutParts }) {
+  const { t, destinations, metaFor, onDestinationClick } = parts;
+  return (
+    <div style={{ display: "flex", flexWrap: "wrap", justifyContent: "center", gap: 14 }}>
+      {destinations.map((d) => {
+        const meta = metaFor(d.platform);
+        return (
+          <a
+            key={d.platform}
+            {...anchorProps(d.platform, d.url, onDestinationClick)}
+            aria-label={meta.label}
+            title={meta.label}
+            style={{
+              width: 54,
+              height: 54,
+              borderRadius: 999,
+              border: `1px solid ${t.border}`,
+              background: t.surface,
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              textDecoration: "none",
+            }}
+          >
+            <ServiceMark platform={d.platform} meta={meta} surface={t.surface} text={t.text} size={24} />
+          </a>
+        );
+      })}
+    </div>
+  );
+}
+
+/**
+ * Full-width pills filled with the service's own colour.
+ *
+ * The label is white or near-black depending on the fill, so a pale brand
+ * (Audiomack's orange, Spotify's green) does not end up as white-on-yellow.
+ */
+function ServicePills({ parts }: { parts: LayoutParts }) {
+  const { t, destinations, metaFor, onDestinationClick } = parts;
+  return (
+    <div style={{ width: "100%", display: "flex", flexDirection: "column", gap: 10 }}>
+      {destinations.map((d) => {
+        const meta = metaFor(d.platform);
+        const fill = MUSIC_SERVICE_ICONS[d.platform]?.hex ?? meta.color;
+        const label = readableBrandColor("#FFFFFF", fill, "#111113", 3);
+        return (
+          <a
+            key={d.platform}
+            {...anchorProps(d.platform, d.url, onDestinationClick)}
+            style={{
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              gap: 10,
+              padding: "14px 18px",
+              borderRadius: 999,
+              background: fill,
+              color: label,
+              textDecoration: "none",
+              fontFamily: t.fontFamily,
+              fontSize: 15,
+              fontWeight: 700,
+            }}
+          >
+            <ServiceMark platform={d.platform} meta={meta} surface={fill} text={label} size={20} />
+            {meta.label}
+          </a>
+        );
+      })}
+    </div>
+  );
+}
+
+const column = (maxWidth: number): CSSProperties => ({
+  width: "100%",
+  maxWidth,
+  display: "flex",
+  flexDirection: "column",
+  alignItems: "center",
+});
+
+/* ──────────────────────────────── layouts ───────────────────────────────── */
+
+function Heading({ parts, align, size }: { parts: LayoutParts; align: "center" | "left"; size: number }) {
+  const { t, link } = parts;
+  return (
+    <>
+      <h1
+        style={{
+          margin: "24px 0 4px",
+          fontSize: size,
+          lineHeight: 1.12,
+          letterSpacing: size > 34 ? "-0.03em" : "-0.01em",
+          textAlign: align,
+          color: t.text,
+          fontFamily: t.headingFontFamily || t.fontFamily,
+          textWrap: "balance",
+        }}
+      >
+        {link.title}
+      </h1>
+      {link.artistName ? (
+        <p style={{ margin: 0, fontSize: 16, color: t.muted, fontFamily: t.fontFamily, textAlign: align }}>
+          {link.artistName}
+        </p>
+      ) : null}
+      {link.description ? (
+        <p style={{ margin: "12px 0 0", fontSize: 14, textAlign: align, color: t.muted, fontFamily: t.fontFamily }}>
+          {link.description}
+        </p>
+      ) : null}
+    </>
+  );
+}
+
+function ListHeading({ parts }: { parts: LayoutParts }) {
+  const { t, listHeading, destinations } = parts;
+  if (!destinations.length) return null;
+  return (
+    <p
+      style={{
+        margin: "28px 0 12px",
+        fontSize: 12,
+        letterSpacing: "0.08em",
+        textTransform: "uppercase",
+        color: t.muted,
+        fontFamily: t.fontFamily,
+      }}
+    >
+      {listHeading}
+    </p>
+  );
+}
+
+function ClassicLayout({ parts }: { parts: LayoutParts }) {
+  return (
+    <div style={column(420)}>
+      {parts.artwork(260)}
+      <Heading parts={parts} align="center" size={24} />
+      <ListHeading parts={parts} />
+      <ServiceRows parts={parts} surface={parts.t.surface} />
+      {parts.pageActions}
+      {parts.footer}
+    </div>
+  );
+}
+
+/**
+ * The cover as the page. Buttons are frosted glass over it, and the type is
+ * always light, because the ground here is the artwork rather than the theme.
+ */
+function ImmersiveLayout({ parts }: { parts: LayoutParts }) {
+  const glass = "rgba(255,255,255,0.14)";
+  const t = { ...parts.t, text: "#ffffff", muted: "rgba(255,255,255,0.72)", border: "rgba(255,255,255,0.22)" };
+  const scoped: LayoutParts = { ...parts, t };
+  return (
+    <div style={{ ...column(430), justifyContent: "flex-end", minHeight: "100%", paddingTop: 40 }}>
+      {/*
+        Deliberately NO cover here. The artwork is already the whole background,
+        and repeating it as a square in the middle is exactly what made this read
+        as Classic with a wallpaper rather than its own thing. What sits in that
+        space instead is the preview control, which has nothing to sit on
+        otherwise.
+      */}
+      {parts.previewButton}
+
+      <h1
+        style={{
+          margin: "26px 0 6px",
+          fontSize: 40,
+          lineHeight: 1.04,
+          letterSpacing: "-0.035em",
+          textAlign: "center",
+          color: "#fff",
+          fontFamily: t.headingFontFamily || t.fontFamily,
+          textWrap: "balance",
+          textShadow: "0 2px 24px rgba(0,0,0,0.5)",
+        }}
+      >
+        {parts.link.title}
+      </h1>
+      {parts.link.artistName ? (
+        <p
+          style={{
+            margin: 0,
+            fontSize: 13,
+            letterSpacing: "0.16em",
+            textTransform: "uppercase",
+            color: "rgba(255,255,255,0.75)",
+            fontFamily: t.fontFamily,
+          }}
+        >
+          {parts.link.artistName}
+        </p>
+      ) : null}
+
+      <div style={{ marginTop: 26, width: "100%" }}>
+        <ServiceRows parts={scoped} surface={glass} />
+      </div>
+      {parts.pageActions}
+      {parts.footer}
+    </div>
+  );
+}
+
+/*
+ * Split needs to be recognisable on a phone too.
+ *
+ * The first version only diverged above 860px, which meant that on the screen
+ * most fans actually use it WAS Classic. Left-aligned type and a two-column
+ * service grid give it an identity from 430px up, and the side-by-side
+ * arrangement is then the widescreen bonus rather than the whole idea.
+ */
+const SPLIT_CSS = `
+.tn-ml-split .tn-ml-split-text { text-align: left; align-items: flex-start; }
+.tn-ml-split .tn-ml-split-text h1,
+.tn-ml-split .tn-ml-split-text p { text-align: left; }
+@media (min-width: 430px) {
+  .tn-ml-split .tn-ml-rows { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; }
+}
+@media (min-width: 860px) {
+  .tn-ml-split { display: grid; grid-template-columns: minmax(0,290px) minmax(0,400px); gap: 46px;
+                 align-items: center; max-width: 780px; }
+  .tn-ml-split .tn-ml-split-art { justify-content: flex-start; }
+}`;
+
+function SplitLayout({ parts }: { parts: LayoutParts }) {
+  return (
+    <>
+      <style>{SPLIT_CSS}</style>
+      <div className="tn-ml-split" style={column(430)}>
+        <div className="tn-ml-split-art" style={{ display: "flex", justifyContent: "center", width: "100%" }}>
+          {parts.artwork(250)}
+        </div>
+        <div className="tn-ml-split-text" style={{ width: "100%", display: "flex", flexDirection: "column" }}>
+          <Heading parts={parts} align="left" size={27} />
+          <ListHeading parts={parts} />
+          <ServiceRows parts={parts} surface={parts.t.surface} />
+          {parts.pageActions}
+          {parts.footer}
+        </div>
+      </div>
+    </>
+  );
+}
+
+/** Type as the hero. The cover shrinks to a credit, and the marks stand alone. */
+function MinimalLayout({ parts }: { parts: LayoutParts }) {
+  return (
+    <div style={column(460)}>
+      {parts.artwork(76)}
+      <Heading parts={parts} align="center" size={44} />
+      <div style={{ marginTop: 30 }}>
+        <ServiceMarks parts={parts} />
+      </div>
+      {parts.pageActions}
+      {parts.footer}
+    </div>
+  );
+}
+
+/** Round cover, brand-filled pills. The fastest to scan. */
+function CompactLayout({ parts }: { parts: LayoutParts }) {
+  return (
+    <div style={column(380)}>
+      <div style={{ borderRadius: 999, overflow: "hidden", lineHeight: 0 }}>{parts.artwork(132)}</div>
+      <Heading parts={parts} align="center" size={22} />
+      <div style={{ marginTop: 22, width: "100%" }}>
+        <ServicePills parts={parts} />
+      </div>
+      {parts.pageActions}
+      {parts.footer}
+    </div>
+  );
+}
+
+const LAYOUTS: Record<MusicLinkStyle, (props: { parts: LayoutParts }) => ReactNode> = {
+  classic: ClassicLayout,
+  immersive: ImmersiveLayout,
+  split: SplitLayout,
+  minimal: MinimalLayout,
+  compact: CompactLayout,
+};
+
+export function MusicLinkLayout({ style, parts }: { style: MusicLinkStyle; parts: LayoutParts }) {
+  const Layout = LAYOUTS[style] ?? ClassicLayout;
+  return <Layout parts={parts} />;
+}

package/src/ui/styled/musicServiceIcons.ts

@@ -0,0 +1,26 @@
+// GENERATED by scripts/generateMusicServiceIcons.mjs. Do not edit by hand.
+//
+// Brand marks and colours from simple-icons. The icons are trademarks of their
+// respective owners and each publishes brand guidelines covering colour and
+// clear space; this renders them unmodified, at their own hex, on a plain
+// ground, which is what those guidelines ask for.
+//
+// Platforms without an entry (amazonMusic, boomplay, anghami, audius) fall back to a
+// brand-coloured initial badge.
+export type MusicServiceIcon = { path: string; hex: string };
+
+export const MUSIC_SERVICE_ICONS: Record<string, MusicServiceIcon> = {
+  spotify: { path: "M12 0C5.4 0 0 5.4 0 12s5.4 12 12 12 12-5.4 12-12S18.66 0 12 0zm5.521 17.34c-.24.359-.66.48-1.021.24-2.82-1.74-6.36-2.101-10.561-1.141-.418.122-.779-.179-.899-.539-.12-.421.18-.78.54-.9 4.56-1.021 8.52-.6 11.64 1.32.42.18.479.659.301 1.02zm1.44-3.3c-.301.42-.841.6-1.262.3-3.239-1.98-8.159-2.58-11.939-1.38-.479.12-1.02-.12-1.14-.6-.12-.48.12-1.021.6-1.141C9.6 9.9 15 10.561 18.72 12.84c.361.181.54.78.241 1.2zm.12-3.36C15.24 8.4 8.82 8.16 5.16 9.301c-.6.179-1.2-.181-1.38-.721-.18-.601.18-1.2.72-1.381 4.26-1.26 11.28-1.02 15.721 1.621.539.3.719 1.02.419 1.56-.299.421-1.02.599-1.559.3z", hex: "#1ED760" },
+  appleMusic: { path: "M23.994 6.124a9.23 9.23 0 00-.24-2.19c-.317-1.31-1.062-2.31-2.18-3.043a5.022 5.022 0 00-1.877-.726 10.496 10.496 0 00-1.564-.15c-.04-.003-.083-.01-.124-.013H5.986c-.152.01-.303.017-.455.026-.747.043-1.49.123-2.193.4-1.336.53-2.3 1.452-2.865 2.78-.192.448-.292.925-.363 1.408-.056.392-.088.785-.1 1.18 0 .032-.007.062-.01.093v12.223c.01.14.017.283.027.424.05.815.154 1.624.497 2.373.65 1.42 1.738 2.353 3.234 2.801.42.127.856.187 1.293.228.555.053 1.11.06 1.667.06h11.03a12.5 12.5 0 001.57-.1c.822-.106 1.596-.35 2.295-.81a5.046 5.046 0 001.88-2.207c.186-.42.293-.87.37-1.324.113-.675.138-1.358.137-2.04-.002-3.8 0-7.595-.003-11.393zm-6.423 3.99v5.712c0 .417-.058.827-.244 1.206-.29.59-.76.962-1.388 1.14-.35.1-.706.157-1.07.173-.95.045-1.773-.6-1.943-1.536a1.88 1.88 0 011.038-2.022c.323-.16.67-.25 1.018-.324.378-.082.758-.153 1.134-.24.274-.063.457-.23.51-.516a.904.904 0 00.02-.193c0-1.815 0-3.63-.002-5.443a.725.725 0 00-.026-.185c-.04-.15-.15-.243-.304-.234-.16.01-.318.035-.475.066-.76.15-1.52.303-2.28.456l-2.325.47-1.374.278c-.016.003-.032.01-.048.013-.277.077-.377.203-.39.49-.002.042 0 .086 0 .13-.002 2.602 0 5.204-.003 7.805 0 .42-.047.836-.215 1.227-.278.64-.77 1.04-1.434 1.233-.35.1-.71.16-1.075.172-.96.036-1.755-.6-1.92-1.544-.14-.812.23-1.685 1.154-2.075.357-.15.73-.232 1.108-.31.287-.06.575-.116.86-.177.383-.083.583-.323.6-.714v-.15c0-2.96 0-5.922.002-8.882 0-.123.013-.25.042-.37.07-.285.273-.448.546-.518.255-.066.515-.112.774-.165.733-.15 1.466-.296 2.2-.444l2.27-.46c.67-.134 1.34-.27 2.01-.403.22-.043.442-.088.663-.106.31-.025.523.17.554.482.008.073.012.148.012.223.002 1.91.002 3.822 0 5.732z", hex: "#FA243C" },
+  itunes: { path: "M11.977 23.999c-2.483 0-4.898-.777-6.954-2.262a11.928 11.928 0 01-4.814-7.806A11.954 11.954 0 012.3 4.994 11.85 11.85 0 0110.08.159a11.831 11.831 0 018.896 2.104 11.933 11.933 0 014.815 7.807 11.958 11.958 0 01-2.091 8.937 11.855 11.855 0 01-7.78 4.835 12.17 12.17 0 01-1.943.157zm-6.474-2.926a11.022 11.022 0 008.284 1.96 11.044 11.044 0 007.246-4.504c3.583-5.003 2.445-12.003-2.538-15.603a11.022 11.022 0 00-8.284-1.96A11.046 11.046 0 002.966 5.47C-.618 10.474.521 17.473 5.503 21.073zm10.606-3.552a2.08 2.08 0 001.458-1.468l.062-.216.008-5.786c.006-4.334 0-5.814-.024-5.895a.535.535 0 00-.118-.214.514.514 0 00-.276-.073c-.073 0-.325.035-.56.078-1.041.19-7.176 1.411-7.281 1.45a.786.786 0 00-.399.354l-.065.128s-.031 9.07-.078 9.172a.7.7 0 01-.376.35 9.425 9.425 0 01-.609.137c-1.231.245-1.688.421-2.075.801-.22.216-.382.51-.453.82-.067.294-.045.736.051 1.005.1.281.262.521.473.71.192.148.419.258.674.324.563.144 1.618-.016 2.158-.328a2.36 2.36 0 00.667-.629c.06-.089.15-.268.2-.399.176-.456.181-8.581.204-8.683a.44.44 0 01.32-.344c.147-.04 6.055-1.207 6.222-1.23.146-.02.284.027.36.12a.29.29 0 01.109.096c.048.07.051.213.058 2.785.008 2.96.012 2.892-.149 3.079-.117.136-.263.189-.864.31-.914.188-1.226.276-1.576.447-.437.213-.679.446-.867.835a1.58 1.58 0 00-.182.754c.001.49.169.871.55 1.245.035.034.069.066.104.097.192.148.387.238.633.294.37.082 1.124.025 1.641-.126z", hex: "#FB5BC5" },
+  youtube: { path: "M23.498 6.186a3.016 3.016 0 0 0-2.122-2.136C19.505 3.545 12 3.545 12 3.545s-7.505 0-9.377.505A3.017 3.017 0 0 0 .502 6.186C0 8.07 0 12 0 12s0 3.93.502 5.814a3.016 3.016 0 0 0 2.122 2.136c1.871.505 9.376.505 9.376.505s7.505 0 9.377-.505a3.015 3.015 0 0 0 2.122-2.136C24 15.93 24 12 24 12s0-3.93-.502-5.814zM9.545 15.568V8.432L15.818 12l-6.273 3.568z", hex: "#FF0000" },
+  youtubeMusic: { path: "M12 0C5.376 0 0 5.376 0 12s5.376 12 12 12 12-5.376 12-12S18.624 0 12 0zm0 19.104c-3.924 0-7.104-3.18-7.104-7.104S8.076 4.896 12 4.896s7.104 3.18 7.104 7.104-3.18 7.104-7.104 7.104zm0-13.332c-3.432 0-6.228 2.796-6.228 6.228S8.568 18.228 12 18.228s6.228-2.796 6.228-6.228S15.432 5.772 12 5.772zM9.684 15.54V8.46L15.816 12l-6.132 3.54z", hex: "#FF0000" },
+  deezer: { path: "M.693 10.024c.381 0 .693-1.256.693-2.807 0-1.55-.312-2.807-.693-2.807C.312 4.41 0 5.666 0 7.217s.312 2.808.693 2.808ZM21.038 1.56c-.364 0-.684.805-.91 2.096C19.765 1.446 19.184 0 18.526 0c-.78 0-1.464 2.036-1.784 5-.312-2.158-.788-3.536-1.325-3.536-.745 0-1.386 2.704-1.62 6.472-.442-1.932-1.083-3.145-1.793-3.145s-1.35 1.213-1.793 3.145c-.242-3.76-.874-6.463-1.628-6.463-.537 0-1.013 1.378-1.325 3.535C6.938 2.036 6.262 0 5.474 0c-.658 0-1.247 1.447-1.602 3.665-.217-1.291-.546-2.105-.91-2.105-.675 0-1.221 2.807-1.221 6.272 0 3.466.546 6.273 1.221 6.273.277 0 .537-.476.736-1.273.32 2.928.996 4.938 1.776 4.938.606 0 1.143-1.204 1.507-3.11.251 3.622.875 6.195 1.602 6.195.46 0 .875-1.023 1.187-2.677C10.142 21.6 11 24 12.004 24c1.005 0 1.863-2.4 2.235-5.822.312 1.654.727 2.677 1.186 2.677.728 0 1.352-2.573 1.603-6.195.364 1.906.9 3.11 1.507 3.11.78 0 1.455-2.01 1.775-4.938.208.797.46 1.273.737 1.273.675 0 1.22-2.807 1.22-6.273-.008-3.457-.553-6.272-1.23-6.272ZM23.307 10.024c.381 0 .693-1.256.693-2.807 0-1.55-.312-2.807-.693-2.807-.381 0-.693 1.256-.693 2.807s.312 2.808.693 2.808Z", hex: "#A238FF" },
+  tidal: { path: "M12.012 3.992L8.008 7.996 4.004 3.992 0 7.996 4.004 12l4.004-4.004L12.012 12l-4.004 4.004 4.004 4.004 4.004-4.004L12.012 12l4.004-4.004-4.004-4.004zM16.042 7.996l3.979-3.979L24 7.996l-3.979 3.979z", hex: "#000000" },
+  soundcloud: { path: "M23.999 14.165c-.052 1.796-1.612 3.169-3.4 3.169h-8.18a.68.68 0 0 1-.675-.683V7.862a.747.747 0 0 1 .452-.724s.75-.513 2.333-.513a5.364 5.364 0 0 1 2.763.755 5.433 5.433 0 0 1 2.57 3.54c.282-.08.574-.121.868-.12.884 0 1.73.358 2.347.992s.948 1.49.922 2.373ZM10.721 8.421c.247 2.98.427 5.697 0 8.672a.264.264 0 0 1-.53 0c-.395-2.946-.22-5.718 0-8.672a.264.264 0 0 1 .53 0ZM9.072 9.448c.285 2.659.37 4.986-.006 7.655a.277.277 0 0 1-.55 0c-.331-2.63-.256-5.02 0-7.655a.277.277 0 0 1 .556 0Zm-1.663-.257c.27 2.726.39 5.171 0 7.904a.266.266 0 0 1-.532 0c-.38-2.69-.257-5.21 0-7.904a.266.266 0 0 1 .532 0Zm-1.647.77a26.108 26.108 0 0 1-.008 7.147.272.272 0 0 1-.542 0 27.955 27.955 0 0 1 0-7.147.275.275 0 0 1 .55 0Zm-1.67 1.769c.421 1.865.228 3.5-.029 5.388a.257.257 0 0 1-.514 0c-.21-1.858-.398-3.549 0-5.389a.272.272 0 0 1 .543 0Zm-1.655-.273c.388 1.897.26 3.508-.01 5.412-.026.28-.514.283-.54 0-.244-1.878-.347-3.54-.01-5.412a.283.283 0 0 1 .56 0Zm-1.668.911c.4 1.268.257 2.292-.026 3.572a.257.257 0 0 1-.514 0c-.241-1.262-.354-2.312-.023-3.572a.283.283 0 0 1 .563 0Z", hex: "#FF5500" },
+  bandcamp: { path: "M0 18.75l7.437-13.5H24l-7.438 13.5H0z", hex: "#408294" },
+  audiomack: { path: "M.331 11.378s.5418-.089.765.1439c.2234.2332.077.7156-.2195.7237-.2965.01-.5705.063-.765-.1439-.1946-.2066-.1424-.6218.2195-.7237m5.881 3.2925c-.0522.01-.1075-.018-.164-.059-.3884-.5413-.5287-2.3923-.707-2.5025-.185-.1144-.8545 1.0255-2.1862.903-.5569-.051-1.1236-.4121-1.4573-.662.031-.4206.0364-1.4027.8659-1.0833.5038.1939 1.3667.7266 2.1245-.23.8378-1.0579 1.2999-.7506 1.577-.5206.2771.23.0925 1.4259.5058 1.0916.4133-.3343 2.082-2.4103 2.082-2.4103s1.292-1.303 1.4898.067c.1979 1.3698 1.0403 2.8877 1.2635 2.8445.2234-.043 2.8223-5.3253 3.1945-5.666.3722-.3409 1.6252-.2961 1.5657.5781-.0596.8742-.1871 6.308-.1871 6.308s-.147 1.5311.0924.7128c.0992-.3392.206-.6453.3392-1.0024.6414-2.0534 1.734-5.5613 2.2784-7.3688.1252-.4325.233-.8037.3166-1.0891l.0001-.0008a3.5925 3.5925 0 0 1 .0973-.3305c.0455-.1532.0763-.2546.0858-.2813.0243-.068.0925-.1192.1884-.157.0962-.061.1995-.064.3165-.067.3021-.027.6907.012 1.0401.1119.1018 0 .2125.037.3172.1118v.0001s.0063 0 .0151.01c.0023 0 .0048 0 .0073.01.0219.015.0573.045.0983.095.0012 0 .0025 0 .004.01.017.021.0341.045.0515.073.1952.2863.315.814.1948 1.7498-.2996 2.3354-.5316 7.1397-.5316 7.1397s-.0461.2298.4353-.782c.0167-.035.0383-.066.058-.098.026-.017.0552-.042.0913-.085.2974-.3546 1.0968-.5629 1.6512-.5586.2336.028.4293.087.5462.1609.2188.333.0897 1.562.0897 1.562-.4612.043-1.3403.2908-1.6519.3366-.3118.046-.7852 2.0699-1.4433 1.8629-.6581-.2069-2.1246-1.1268-2.1246-1.2533 0-.1102.1152-1.4546.1453-1.8016.0022-.024.004-.046.0058-.068a.152.152 0 0 1 .0014-.014l-.0002.0003c.0213-.2733.0023-.3927-.1239-.1199-.1086.2346-.581 1.7359-1.1078 3.3709-.0556.1429-1.0511 3.1558-1.1818 3.5231-.156.4261-.287.7523-.3776.921-.1378.1867-.3234.3036-.5826.2252-.6465-.1954-1.4654-1.0889-1.473-1.3106-.0155-1.2503.0608-7.973-.2423-7.4127-.311.5744-2.73 4.5608-2.73 4.5608-.0405.01-.0705.01-.1062.01-.1712-.019-.4366-.074-.51-.2384-.004-.01-.0094-.018-.0129-.028-.0035-.01-.0075-.022-.0135-.04-.0329-.1097-.0463-.2289-.0753-.3265-.1082-.3652-.2813-.8886-.463-1.421-.2784-.9079-.5654-1.8366-.6127-1.9391-.0923-.2007-.2268-.116-.3475-.0002-.54.458-1.6868 2.4793-2.7225 2.5898", hex: "#FFA200" },
+  pandora: { path: "M1.882 0v24H8.32a1.085 1.085 0 001.085-1.085v-4.61h1.612c7.88 0 11.103-4.442 11.103-9.636C22.119 2.257 17.247 0 12.662 0H1.882Z", hex: "#224099" },
+  napster: { path: "M20.495 4.543c-.22 0-.438 0-.657.03h-.031l-.032-.03C17.93 2.21 15.02.798 12.015.798c-3.004 0-5.945 1.412-7.76 3.775l-.031.03h-.031c-.22-.03-.439-.03-.658-.03H2.16v2.394l-.032.03A3.628 3.628 0 0 0 0 10.282c0 1.412.844 2.701 2.127 3.284h.063v.062c.031 5.278 4.443 9.575 9.825 9.575s9.794-4.297 9.825-9.575v-.062l.032-.03C23.155 12.92 24 11.632 24 10.25c0-1.412-.845-2.7-2.128-3.284l-.032-.03V4.542zM6.821 5.34a7.443 7.443 0 0 1 5.194-2.117c1.94 0 3.818.767 5.195 2.117l.062.062-.094.061c-.375.215-.72.43-1.064.675l-.03.031-.032-.03c-.908-.461-2.347-.983-4.005-.983s-3.098.522-4.006.982l-.03.031-.032-.03a10.22 10.22 0 0 0-1.064-.676l-.188-.061zm12.329 8.195c0 3.866-3.223 7.027-7.166 7.027-3.942 0-7.134-3.16-7.134-7.027V7.458l.094.03c1.252.308 2.44 1.658 2.722 1.996.313-.338 1.784-1.658 4.35-1.658 2.565 0 4.036 1.35 4.35 1.658.28-.338 1.438-1.688 2.721-1.995l.094-.031v6.077z", hex: "#2259FF" },
+  tiktok: { path: "M12.525.02c1.31-.02 2.61-.01 3.91-.02.08 1.53.63 3.09 1.75 4.17 1.12 1.11 2.7 1.62 4.24 1.79v4.03c-1.44-.05-2.89-.35-4.2-.97-.57-.26-1.1-.59-1.62-.93-.01 2.92.01 5.84-.02 8.75-.08 1.4-.54 2.79-1.35 3.94-1.31 1.92-3.58 3.17-5.91 3.21-1.43.08-2.86-.31-4.08-1.03-2.02-1.19-3.44-3.37-3.65-5.71-.02-.5-.03-1-.01-1.49.18-1.9 1.12-3.72 2.58-4.96 1.66-1.44 3.98-2.13 6.15-1.72.02 1.48-.04 2.96-.04 4.44-.99-.32-2.15-.23-3.02.37-.63.41-1.11 1.04-1.36 1.75-.21.51-.15 1.07-.14 1.61.24 1.64 1.82 3.02 3.5 2.87 1.12-.01 2.19-.66 2.77-1.61.19-.33.4-.67.41-1.06.1-1.79.06-3.57.07-5.36.01-4.03-.01-8.05.02-12.07z", hex: "#000000" },
+};

package/src/utils/contrast.ts

@@ -0,0 +1,60 @@
+/**
+ * WCAG relative luminance and contrast ratio, for deciding whether a colour is
+ * actually visible on a given background.
+ *
+ * This exists because brand colours cannot be rendered blindly. Several music
+ * services use pure black as their mark (Tidal, TikTok), which is 19:1 on a
+ * white page and 1.17:1 on a dark one, meaning it does not render at all on a
+ * dark theme. Trusting the brand hex on a themeable page ships an invisible
+ * logo to whichever half of creators picked the other background.
+ */
+
+const channel = (value: number) => (value <= 0.03928 ? value / 12.92 : Math.pow((value + 0.055) / 1.055, 2.4));
+
+/** WCAG relative luminance of a `#rgb` or `#rrggbb` colour. `null` if unparseable. */
+export function relativeLuminance(hex: string): number | null {
+  const value = hex.trim().replace("#", "");
+  const full =
+    value.length === 3
+      ? value
+          .split("")
+          .map((c) => c + c)
+          .join("")
+      : value;
+  if (!/^[0-9a-fA-F]{6}$/.test(full)) return null;
+
+  const [r, g, b] = [0, 2, 4].map((i) => channel(parseInt(full.slice(i, i + 2), 16) / 255));
+  return 0.2126 * r! + 0.7152 * g! + 0.0722 * b!;
+}
+
+/** Contrast ratio between two colours, 1 to 21. `null` if either is unparseable. */
+export function contrastRatio(a: string, b: string): number | null {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  if (la === null || lb === null) return null;
+  const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * The brand colour where it is legible, the fallback where it is not.
+ *
+ * The threshold is 2.0 rather than WCAG's 3:1 for non-text content, and that is
+ * a deliberate trade rather than an oversight. These are logo silhouettes whose
+ * SHAPE carries the recognition, and the brands themselves ship them at ratios
+ * below 3:1 (Spotify green on white is 1.76:1, and Spotify's own guidelines
+ * permit exactly that). Holding to 3:1 would repaint most of the marks a flat
+ * theme colour and throw away the recognition that makes them worth using.
+ *
+ * 2.0 catches only what genuinely disappears, which in practice is the pure
+ * black marks on a dark background. Those brands all publish a monochrome
+ * variant for dark surfaces, so swapping to the theme's own text colour is what
+ * their guidelines ask for anyway.
+ */
+export function readableBrandColor(brand: string, background: string, fallback: string, min = 2.0): string {
+  const ratio = contrastRatio(brand, background);
+  // Unparseable means unknown, and an unknown colour is not worth risking an
+  // invisible logo over.
+  if (ratio === null) return fallback;
+  return ratio >= min ? brand : fallback;
+}