nixamp 0.60.0 → 0.60.2

package/dist/music-hub.d.ts

@@ -87,6 +87,8 @@ export interface MusicRoutesContext {
     readBody: (request: IncomingMessage) => Promise<string>;
     /** The page shell (web/music.html), or null when the web build is absent. */
     page: () => string | null;
+    /** This site's public origin, for canonical and og: addresses (https://nixamp.com). */
+    site?: string;
     /** A server says something of its label landed; null when nobody may say so. */
     released?: (request: IncomingMessage, body: Record<string, unknown>) => Promise<{
         status: number;

package/dist/music-hub.js

@@ -12,6 +12,7 @@
  *   POST /api/v1/music/released               a server says an album or song landed: its followers hear
  */
 import { createHash } from "node:crypto";
+import { musicPage, renderMusicPage } from "./music-seo.js";
 /** A server's opaque id: the first 10 hex of the SHA-256 of its https origin. Both sides can work it out. */
 export function serverId(base) {
     return createHash("sha256").update(base.replace(/\/+$/, "")).digest("hex").slice(0, 10);
@@ -221,13 +222,28 @@ export async function handleMusicRoutes(request, response, path, ctx) {
         }
         return true;
     }
-    // /music and everything under it is the app; it reads /api/v1/music.
-    const page = ctx.page();
-    if (!page) {
+    // /music and everything under it is the app; it reads /api/v1/music. Its head and a
+    // plain summary are written here, per page (music-seo.ts), for crawlers and link
+    // previews; a catalogue that is slow or gone leaves the shell as it is.
+    const shell = ctx.page();
+    if (!shell) {
         ctx.json(response, 404, { error: "the music app is not built here" });
         return true;
     }
-    response.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-cache" });
-    response.end(method === "HEAD" ? undefined : page);
+    const site = (ctx.site ?? "https://nixamp.com").replace(/\/+$/, "");
+    const catalogue = await Promise.race([
+        ctx.hub.catalogue().catch(() => null),
+        new Promise((done) => setTimeout(() => done(null), 2_000).unref?.()),
+    ]);
+    // An empty catalogue (nixamp.com just restarted, no server has said hello yet) or
+    // one without the server a page names is not knowing, not "no such page": the
+    // shell as it is, never a 404 a crawler would drop the page for.
+    const servers = new Set(catalogue?.genres.flatMap((one) => one.artists.map((artist) => artist.server)) ?? []);
+    const named = /^\/music\/(?:artist|album)\/([a-f0-9]{10})\//.exec(path)?.[1];
+    const known = servers.size > 0 && (!named || servers.has(named));
+    const view = catalogue && known ? musicPage(path, catalogue, site) : null;
+    const html = view ? renderMusicPage(shell, view, `${site}${path.replace(/\/+$/, "") || "/music"}`) : shell;
+    response.writeHead(view?.status ?? 200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-cache" });
+    response.end(method === "HEAD" ? undefined : html);
     return true;
 }

package/dist/music-seo.d.ts

@@ -0,0 +1,38 @@
+/**
+ * nixamp.com/music for crawlers and link previews: the page shell with its
+ * head and a plain summary written on the server, per page. The app reads
+ * /api/v1/music and replaces the summary when its script runs, so a person
+ * sees the app and a crawler, a chat app or a social card sees the title,
+ * the artist, the album and its artwork without running anything.
+ *
+ *   /music                                  the label: genres, artists, stations
+ *   /music/genre/<slug>                     a genre's artists
+ *   /music/artist/<server>/<artist>         an artist: bio, members, albums
+ *   /music/album/<server>/<artist>/<album>  an album: cover, songs
+ *   /music/me                               the listener's own page: never indexed
+ */
+import type { HubCatalogue } from "./music-hub.ts";
+interface Head {
+    title: string;
+    description: string;
+    type: string;
+    image?: {
+        url: string;
+        alt: string;
+    };
+    noindex?: boolean;
+    /** og:music:* and similar, as [property, content]. */
+    extra?: Array<[string, string]>;
+    ld?: Record<string, unknown>;
+}
+/** What the server writes for a /music address: its head, and a summary for the page body. */
+export interface MusicPage {
+    head: Head;
+    body: string;
+    status: number;
+}
+/** The head and summary of a /music address, from the catalogue. `site` is https://nixamp.com. */
+export declare function musicPage(path: string, catalogue: HubCatalogue, site: string): MusicPage;
+/** The shell with a page's head and summary written in. */
+export declare function renderMusicPage(shell: string, page: MusicPage, url: string): string;
+export {};

package/dist/music-seo.js

@@ -0,0 +1,160 @@
+const slug = (text) => text.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+const escape = (text) => text.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const clip = (text, max) => {
+    const one = text.replace(/\s+/g, " ").trim();
+    return one.length <= max ? one : `${one.slice(0, max - 1).replace(/\s+\S*$/, "")}…`;
+};
+const clock = (seconds) => `${Math.floor(seconds / 60)}:${String(Math.round(seconds % 60)).padStart(2, "0")}`;
+/** The head and summary of a /music address, from the catalogue. `site` is https://nixamp.com. */
+export function musicPage(path, catalogue, site) {
+    const at = (rest) => `${site}${rest}`;
+    const file = (server, rest) => at(`/api/v1/music/file/${server}/${rest}`);
+    const artists = catalogue.genres.flatMap((genre) => genre.artists);
+    const holder = catalogue.holders[0] ?? "Profullstack, Inc.";
+    const parts = path.replace(/\/+$/, "").split("/").slice(2);
+    const pictureOf = (artist) => {
+        const album = [...artist.albums].reverse().find((one) => one.cover);
+        if (album)
+            return { url: file(artist.server, `${artist.key}/${album.key}/cover.jpg`), alt: `${album.title} by ${artist.name}, the cover` };
+        const member = artist.members?.[0];
+        return member ? { url: file(artist.server, `${artist.key}/members/${member.slug}.jpg`), alt: `${member.name} of ${artist.name}` } : undefined;
+    };
+    const artistLink = (artist) => `/music/artist/${artist.server}/${artist.key}`;
+    const missing = (what) => ({
+        status: 404,
+        head: { title: `No such ${what} · nixamp music`, description: `Nothing by that name is on nixamp music.`, type: "website", noindex: true },
+        body: `<h1>No such ${escape(what)}</h1><p><a href="/music">Every artist on nixamp music</a></p>`,
+    });
+    if (parts[0] === "me") {
+        return {
+            status: 200,
+            head: { title: "My music · nixamp", description: "The songs and albums you bought on nixamp, and the artists you follow.", type: "website", noindex: true },
+            body: "<h1>My music</h1><p>Sign in to see what you bought and who you follow.</p>",
+        };
+    }
+    if (parts[0] === "genre" && parts[1]) {
+        const genre = catalogue.genres.find((one) => slug(one.genre) === parts[1]);
+        if (!genre)
+            return missing("genre");
+        const names = genre.artists.map((one) => one.name);
+        const lead = genre.artists[0];
+        return {
+            status: 200,
+            head: {
+                title: `${genre.genre} · nixamp music`,
+                description: clip(`${genre.genre} by AI artists on nixamp: ${names.join(", ")}. Listen free on the live station; follow the artists; buy the songs.`, 200),
+                type: "website",
+                ...(lead && pictureOf(lead) ? { image: pictureOf(lead) } : {}),
+            },
+            body: `<h1>${escape(genre.genre)}</h1><ul>${genre.artists.map((one) => `<li><a href="${artistLink(one)}">${escape(one.name)}</a>${one.bio ? `: ${escape(clip(one.bio, 160))}` : ""}</li>`).join("")}</ul>`,
+        };
+    }
+    if (parts[0] === "artist" && parts[1] && parts[2]) {
+        const artist = artists.find((one) => one.server === parts[1] && one.key === parts[2]);
+        if (!artist)
+            return missing("artist");
+        const image = pictureOf(artist);
+        const albums = artist.albums.filter((one) => one.songs.length > 0);
+        const members = artist.members ?? [];
+        return {
+            status: 200,
+            head: {
+                title: `${artist.name} · ${artist.genre} · nixamp music`,
+                description: clip(artist.bio || `${artist.name}, ${artist.genre} on nixamp: ${albums.length} album${albums.length === 1 ? "" : "s"}.`, 200),
+                type: "profile",
+                ...(image ? { image } : {}),
+                ld: {
+                    "@context": "https://schema.org", "@type": "MusicGroup", name: artist.name, genre: artist.genre, url: at(artistLink(artist)),
+                    ...(artist.bio ? { description: artist.bio } : {}),
+                    ...(image ? { image: image.url } : {}),
+                    ...(members.length ? { member: members.map((one) => ({ "@type": "Person", name: one.name, ...(one.role ? { roleName: one.role } : {}) })) } : {}),
+                    album: albums.map((one) => ({ "@type": "MusicAlbum", name: one.title, url: at(`/music/album/${artist.server}/${artist.key}/${one.key}`), ...(one.year ? { datePublished: String(one.year) } : {}) })),
+                    recordLabel: { "@type": "Organization", name: holder },
+                },
+            },
+            body: `<p><a href="/music">Music</a> / <a href="/music/genre/${slug(artist.genre)}">${escape(artist.genre)}</a></p><h1>${escape(artist.name)}</h1>`
+                + (artist.bio ? `<p>${escape(artist.bio)}</p>` : "")
+                + (members.length ? `<h2>Members</h2><ul>${members.map((one) => `<li>${escape(one.name)}${one.role ? `, ${escape(one.role)}` : ""}</li>`).join("")}</ul>` : "")
+                + (albums.length ? `<h2>Albums</h2><ul>${albums.map((one) => `<li><a href="/music/album/${artist.server}/${artist.key}/${one.key}">${escape(one.title)}</a>${one.year ? ` (${one.year})` : ""}</li>`).join("")}</ul>` : ""),
+        };
+    }
+    if (parts[0] === "album" && parts[1] && parts[2] && parts[3]) {
+        const artist = artists.find((one) => one.server === parts[1] && one.key === parts[2]);
+        const album = artist?.albums.find((one) => one.key === parts[3]);
+        if (!artist || !album)
+            return missing("album");
+        const image = album.cover ? { url: file(artist.server, `${artist.key}/${album.key}/cover.jpg`), alt: `${album.title} by ${artist.name}, the cover` } : pictureOf(artist);
+        const url = at(`/music/album/${artist.server}/${artist.key}/${album.key}`);
+        return {
+            status: 200,
+            head: {
+                title: `${album.title} by ${artist.name} · nixamp music`,
+                description: clip(album.concept || `${album.title}, ${album.songs.length} songs by ${artist.name} (${artist.genre})${album.year ? `, ${album.year}` : ""}. Listen free on nixamp.`, 200),
+                type: "music.album",
+                ...(image ? { image } : {}),
+                extra: [
+                    ["music:musician", at(artistLink(artist))],
+                    ...(album.year ? [["music:release_date", String(album.year)]] : []),
+                    ...album.songs.slice(0, 30).map((song) => ["music:song", `${url}#${song.n}`]),
+                ],
+                ld: {
+                    "@context": "https://schema.org", "@type": "MusicAlbum", name: album.title, url,
+                    byArtist: { "@type": "MusicGroup", name: artist.name, url: at(artistLink(artist)) },
+                    genre: artist.genre, numTracks: album.songs.length,
+                    ...(album.year ? { datePublished: String(album.year) } : {}),
+                    ...(image ? { image: image.url } : {}),
+                    ...(album.concept ? { description: album.concept } : {}),
+                    recordLabel: { "@type": "Organization", name: holder },
+                    track: album.songs.map((song) => ({ "@type": "MusicRecording", name: song.title, position: song.n, ...(song.seconds ? { duration: `PT${Math.floor(song.seconds / 60)}M${Math.round(song.seconds % 60)}S` } : {}) })),
+                },
+            },
+            body: `<p><a href="/music">Music</a> / <a href="${artistLink(artist)}">${escape(artist.name)}</a></p><h1>${escape(album.title)}</h1>`
+                + `<p>by <a href="${artistLink(artist)}">${escape(artist.name)}</a>${album.year ? ` · ${album.year}` : ""} · ${album.songs.length} songs</p>`
+                + (album.concept ? `<p>${escape(album.concept)}</p>` : "")
+                + `<ol>${album.songs.map((song) => `<li>${escape(song.title)}${song.seconds ? ` <span>${clock(song.seconds)}</span>` : ""}</li>`).join("")}</ol>`,
+        };
+    }
+    if (parts.length > 0)
+        return missing("page");
+    const lead = artists.find((one) => pictureOf(one));
+    return {
+        status: 200,
+        head: {
+            title: "AI music, live and on demand · nixamp",
+            description: clip(`Original bands and artists, written and sung by AI and released by ${holder}: ${catalogue.genres.map((one) => one.genre).join(", ")}. Listen free; follow the artists; buy the songs.`, 200),
+            type: "website",
+            ...(lead ? { image: pictureOf(lead) } : {}),
+        },
+        body: `<h1>AI music, live and on demand</h1>${catalogue.genres.map((genre) => `<h2><a href="/music/genre/${slug(genre.genre)}">${escape(genre.genre)}</a></h2><ul>${genre.artists.map((one) => `<li><a href="${artistLink(one)}">${escape(one.name)}</a></li>`).join("")}</ul>`).join("")}`,
+    };
+}
+/** The shell with a page's head and summary written in. */
+export function renderMusicPage(shell, page, url) {
+    const { head } = page;
+    const meta = [
+        `<title>${escape(head.title)}</title>`,
+        `<meta name="description" content="${escape(head.description)}" />`,
+        `<link rel="canonical" href="${escape(url)}" />`,
+        ...(head.noindex ? [`<meta name="robots" content="noindex" />`] : []),
+        `<meta property="og:site_name" content="nixamp" />`,
+        `<meta property="og:title" content="${escape(head.title.replace(/ · nixamp( music)?$/, ""))}" />`,
+        `<meta property="og:description" content="${escape(head.description)}" />`,
+        `<meta property="og:type" content="${escape(head.type)}" />`,
+        `<meta property="og:url" content="${escape(url)}" />`,
+        ...(head.image ? [
+            `<meta property="og:image" content="${escape(head.image.url)}" />`,
+            `<meta property="og:image:alt" content="${escape(head.image.alt)}" />`,
+            `<meta name="twitter:card" content="summary_large_image" />`,
+            `<meta name="twitter:image" content="${escape(head.image.url)}" />`,
+        ] : [`<meta name="twitter:card" content="summary" />`]),
+        `<meta name="twitter:title" content="${escape(head.title)}" />`,
+        `<meta name="twitter:description" content="${escape(head.description)}" />`,
+        ...(head.extra ?? []).map(([property, content]) => `<meta property="${escape(property)}" content="${escape(content)}" />`),
+        ...(head.ld ? [`<script type="application/ld+json">${JSON.stringify(head.ld).replace(/</g, "\\u003c")}</script>`] : []),
+    ];
+    return shell
+        .replace(/<title>[^<]*<\/title>/, "")
+        .replace(/<meta name="description"[^>]*>/, "")
+        .replace("</head>", `    ${meta.join("\n    ")}\n  </head>`)
+        .replace(/(<main id="view"[^>]*>)(<\/main>)/, `$1${page.body}$2`);
+}

package/dist/radio-pages.d.ts

@@ -188,9 +188,11 @@ export interface StationFace {
     description?: string;
     video?: boolean;
 }
-export declare function stationHead(station: StationFace, slug: string, base: string, path?: string): string;
+export declare function stationHead(station: StationFace, slug: string, base: string, path?: string, image?: string): string;
+/** A station's picture for link previews: the cover of an album it plays, from the catalogue. */
+export declare function stationImage(catalogue: RadioCatalogue, slug: string, base: string): string;
 /** The built station page (or the inline one) as /radio/<name> serves it: its head, the header, indexable. */
-export declare function asRadioPage(html: string, station: StationFace, slug: string, base: string, nav: string, path?: string): string;
+export declare function asRadioPage(html: string, station: StationFace, slug: string, base: string, nav: string, path?: string, image?: string): string;
 /** A station another server lists on this guide (a guide peer), as /radio reaches it. */
 export interface PeerRadio {
     origin: string;

package/dist/radio-pages.js

@@ -388,7 +388,7 @@ export function renderAlbum(catalogue, album, ctx) {
 export function renderMissing(what, base, nav) {
     return document({ title: `Not here · live.streaming`, description: "Nothing by that name is on the air here.", url: `${base}/radio` }, nav, `<h1>No ${escape(what)} by that name</h1><p class="lead">Nothing by that name is on the air here now. <a href="/radio">See every station</a>.</p>`);
 }
-export function stationHead(station, slug, base, path = `/radio/${slug}`) {
+export function stationHead(station, slug, base, path = `/radio/${slug}`, image = "") {
     const url = `${base}${path}`;
     const description = station.description || `${station.name}, live now. Free to listen; tap the artist or album on the air to see more.`;
     return `<title>${escape(station.name)} · live.streaming</title>
@@ -399,13 +399,20 @@ export function stationHead(station, slug, base, path = `/radio/${slug}`) {
     <meta property="og:url" content="${escape(url)}" />
     <meta property="og:type" content="${station.video ? "video.tv_show" : "music.radio_station"}" />
     <meta property="og:site_name" content="live.streaming" />
-    <meta name="twitter:card" content="summary" />
+    ${image ? `<meta property="og:image" content="${escape(image)}" />
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:image" content="${escape(image)}" />` : `<meta name="twitter:card" content="summary" />`}
     <style>${NAV_STYLE}</style>`;
 }
+/** A station's picture for link previews: the cover of an album it plays, from the catalogue. */
+export function stationImage(catalogue, slug, base) {
+    const album = [...catalogue.albums.values()].find((one) => one.stations.includes(slug) && (one.coverFile || one.label?.cover));
+    return album ? `${base}/radio/album/${album.slug}/cover.jpg` : "";
+}
 /** The built station page (or the inline one) as /radio/<name> serves it: its head, the header, indexable. */
-export function asRadioPage(html, station, slug, base, nav, path) {
+export function asRadioPage(html, station, slug, base, nav, path, image = "") {
     return html
-        .replace(/<title>[^<]*<\/title>/, stationHead(station, slug, base, path))
+        .replace(/<title>[^<]*<\/title>/, stationHead(station, slug, base, path, image))
         .replace(/\s*<meta name="robots" content="noindex"\s*\/?>/, "")
         .replace(/<body>/, `<body>\n${nav}`);
 }

package/dist/server.js

@@ -79,7 +79,7 @@ import { handleRoomProxy, handleRooms, isRoomPath, ROOM_PAGE, roomAddress, RoomP
 import { handleVods, VodProbe, vodEntries, VodStore, vodView } from "./guide-vods.js";
 import { withPitFooter } from "./pit-footer.js";
 import { handleFollowPage } from "./follow-page.js";
-import { asRadioPage, buildCatalogue, isRadioPath, NAV_STYLE, RADIO_ALBUM, RADIO_ARTIST, RADIO_CSP, RADIO_STATION, RADIO_SUB, RADIO_BUY, radioBuyLink, radioBuyQuery, radioNav, radioPeers, radioRewriter, radioStations, renderAlbum, renderArtist, renderDirectory, renderMissing, rewriteResponse, } from "./radio-pages.js";
+import { asRadioPage, buildCatalogue, isRadioPath, NAV_STYLE, RADIO_ALBUM, RADIO_ARTIST, RADIO_CSP, RADIO_STATION, RADIO_SUB, RADIO_BUY, radioBuyLink, radioBuyQuery, radioNav, radioPeers, radioRewriter, radioStations, renderAlbum, stationImage, renderArtist, renderDirectory, renderMissing, rewriteResponse, } from "./radio-pages.js";
 import { adCsp, guideAds, guideCsp, withPageAd, guideHosts, guidePeers, peerBase, PeerGuides, renderGuide } from "./station-guide.js";
 import { StationRunner } from "./station-runner.js";
 import { StationError, StationStore, channelOf, stationOfChannel } from "./stations.js";
@@ -2291,6 +2291,15 @@ export function createHandler(engine, options) {
         const requestHost = String(request.headers["x-forwarded-host"] ?? request.headers.host ?? "").split(",")[0].trim().replace(/:\d+$/, "").toLowerCase();
         const isGuidePage = Boolean(options.stations) && (request.method === "GET" || request.method === "HEAD") &&
             (path === "/guide" || (path === "/" && guideHosts().has(requestHost)));
+        // nixamp.com's own /radio is the radio app (web/radio.html), not live.streaming's
+        // station list; its other /radio pages name nixamp.com, not the box behind it.
+        const onDirectory = (() => { try {
+            return new URL(storeSite).host === requestHost;
+        }
+        catch {
+            return false;
+        } })();
+        const radioPath = isRadioPath(path) && !(onDirectory && (path === "/radio" || path === "/radio/"));
         // The built web bundle is the same public code nixamp.com hands anyone;
         // a station's page loads it, and a station link carries no server key.
         const isPublicAsset = (request.method === "GET" || request.method === "HEAD") &&
@@ -2330,7 +2339,7 @@ export function createHandler(engine, options) {
             !((path === "/vod" || /^\/vod\/[A-Za-z0-9_-]{1,32}$/.test(path) || path === "/api/v1/guide/vods" || path.startsWith("/api/v1/guide/vods/")) && Boolean(options.stations?.vods)) &&
             !STATION_PAGE.test(path) &&
             // Public, listed stations under readable names, and their artists and albums (radio-pages.ts).
-            !(isRadioPath(path) && Boolean(options.stations)) &&
+            !(radioPath && Boolean(options.stations)) &&
             // Following an artist from those pages, signed in at nixamp.com.
             !(path === "/follow" && Boolean(options.follows && options.accounts)) &&
             !isPublicAsset &&
@@ -2657,11 +2666,11 @@ export function createHandler(engine, options) {
                 return;
             }
         }
-        if (options.stations && isRadioPath(path) && (request.method === "GET" || request.method === "HEAD")) {
+        if (options.stations && radioPath && (request.method === "GET" || request.method === "HEAD")) {
             const stations = options.stations;
             const named = radioStations(stations.store.list());
             const publicBase = stations.publicBase?.() ?? "";
-            const base = radioBaseFor(request, publicBase);
+            const base = onDirectory ? storeSite : radioBaseFor(request, publicBase);
             const nav = radioNav(guideHosts().has(requestHost) ? "/" : "/guide");
             const send = (status, page, csp = RADIO_CSP) => {
                 const ads = guideAds();
@@ -2765,7 +2774,9 @@ export function createHandler(engine, options) {
                 const built = web !== null && isFile(join(web, "station.html")) ? readFileSync(join(web, "station.html"), "utf8") : null;
                 // The built page carries the one ad; the inline fallback stays as it is.
                 const ads = built ? guideAds() : {};
-                const page = withPageAd(asRadioPage(built ?? STATION_PAGE_HTML, station, slug, base, nav), ads);
+                // Its link preview carries the cover of an album it plays.
+                const image = stationImage(radioCatalogue(), slug, base);
+                const page = withPageAd(asRadioPage(built ?? STATION_PAGE_HTML, station, slug, base, nav, undefined, image), ads);
                 response.writeHead(200, {
                     "content-type": "text/html; charset=utf-8",
                     "cache-control": "no-cache",
@@ -2888,6 +2899,7 @@ export function createHandler(engine, options) {
                 catch {
                     return null;
                 } },
+                site: storeSite,
                 released: music.released,
                 ...(music.veo ? { veo: music.veo } : {}),
             }))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.60.0",
+  "version": "0.60.2",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",

package/src/music-hub.ts

@@ -13,6 +13,7 @@
  */
 import { createHash } from "node:crypto";
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { musicPage, renderMusicPage } from "./music-seo.ts";
 
 /** A server's opaque id: the first 10 hex of the SHA-256 of its https origin. Both sides can work it out. */
 export function serverId(base: string): string {
@@ -158,6 +159,8 @@ export interface MusicRoutesContext {
   readBody: (request: IncomingMessage) => Promise<string>;
   /** The page shell (web/music.html), or null when the web build is absent. */
   page: () => string | null;
+  /** This site's public origin, for canonical and og: addresses (https://nixamp.com). */
+  site?: string;
   /** A server says something of its label landed; null when nobody may say so. */
   released?: (request: IncomingMessage, body: Record<string, unknown>) => Promise<{ status: number; body: unknown }>;
   /** Veo shots for a label server's videos: the month's spend (GET), a clip (POST); answers bytes or JSON. */
@@ -215,10 +218,25 @@ export async function handleMusicRoutes(request: IncomingMessage, response: Serv
     }
     return true;
   }
-  // /music and everything under it is the app; it reads /api/v1/music.
-  const page = ctx.page();
-  if (!page) { ctx.json(response, 404, { error: "the music app is not built here" }); return true; }
-  response.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-cache" });
-  response.end(method === "HEAD" ? undefined : page);
+  // /music and everything under it is the app; it reads /api/v1/music. Its head and a
+  // plain summary are written here, per page (music-seo.ts), for crawlers and link
+  // previews; a catalogue that is slow or gone leaves the shell as it is.
+  const shell = ctx.page();
+  if (!shell) { ctx.json(response, 404, { error: "the music app is not built here" }); return true; }
+  const site = (ctx.site ?? "https://nixamp.com").replace(/\/+$/, "");
+  const catalogue = await Promise.race([
+    ctx.hub.catalogue().catch(() => null),
+    new Promise<null>((done) => setTimeout(() => done(null), 2_000).unref?.()),
+  ]);
+  // An empty catalogue (nixamp.com just restarted, no server has said hello yet) or
+  // one without the server a page names is not knowing, not "no such page": the
+  // shell as it is, never a 404 a crawler would drop the page for.
+  const servers = new Set(catalogue?.genres.flatMap((one) => one.artists.map((artist) => artist.server)) ?? []);
+  const named = /^\/music\/(?:artist|album)\/([a-f0-9]{10})\//.exec(path)?.[1];
+  const known = servers.size > 0 && (!named || servers.has(named));
+  const view = catalogue && known ? musicPage(path, catalogue, site) : null;
+  const html = view ? renderMusicPage(shell, view, `${site}${path.replace(/\/+$/, "") || "/music"}`) : shell;
+  response.writeHead(view?.status ?? 200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-cache" });
+  response.end(method === "HEAD" ? undefined : html);
   return true;
 }

package/src/music-seo.ts

@@ -0,0 +1,191 @@
+/**
+ * nixamp.com/music for crawlers and link previews: the page shell with its
+ * head and a plain summary written on the server, per page. The app reads
+ * /api/v1/music and replaces the summary when its script runs, so a person
+ * sees the app and a crawler, a chat app or a social card sees the title,
+ * the artist, the album and its artwork without running anything.
+ *
+ *   /music                                  the label: genres, artists, stations
+ *   /music/genre/<slug>                     a genre's artists
+ *   /music/artist/<server>/<artist>         an artist: bio, members, albums
+ *   /music/album/<server>/<artist>/<album>  an album: cover, songs
+ *   /music/me                               the listener's own page: never indexed
+ */
+import type { HubArtist, HubCatalogue } from "./music-hub.ts";
+
+const slug = (text: string): string => text.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+const escape = (text: string): string => text.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]!);
+const clip = (text: string, max: number): string => {
+  const one = text.replace(/\s+/g, " ").trim();
+  return one.length <= max ? one : `${one.slice(0, max - 1).replace(/\s+\S*$/, "")}…`;
+};
+const clock = (seconds: number): string => `${Math.floor(seconds / 60)}:${String(Math.round(seconds % 60)).padStart(2, "0")}`;
+
+interface Head {
+  title: string;
+  description: string;
+  type: string;
+  image?: { url: string; alt: string };
+  noindex?: boolean;
+  /** og:music:* and similar, as [property, content]. */
+  extra?: Array<[string, string]>;
+  ld?: Record<string, unknown>;
+}
+
+/** What the server writes for a /music address: its head, and a summary for the page body. */
+export interface MusicPage { head: Head; body: string; status: number }
+
+/** The head and summary of a /music address, from the catalogue. `site` is https://nixamp.com. */
+export function musicPage(path: string, catalogue: HubCatalogue, site: string): MusicPage {
+  const at = (rest: string): string => `${site}${rest}`;
+  const file = (server: string, rest: string): string => at(`/api/v1/music/file/${server}/${rest}`);
+  const artists = catalogue.genres.flatMap((genre) => genre.artists);
+  const holder = catalogue.holders[0] ?? "Profullstack, Inc.";
+  const parts = path.replace(/\/+$/, "").split("/").slice(2);
+  const pictureOf = (artist: HubArtist): Head["image"] => {
+    const album = [...artist.albums].reverse().find((one) => one.cover);
+    if (album) return { url: file(artist.server, `${artist.key}/${album.key}/cover.jpg`), alt: `${album.title} by ${artist.name}, the cover` };
+    const member = artist.members?.[0];
+    return member ? { url: file(artist.server, `${artist.key}/members/${member.slug}.jpg`), alt: `${member.name} of ${artist.name}` } : undefined;
+  };
+  const artistLink = (artist: HubArtist): string => `/music/artist/${artist.server}/${artist.key}`;
+  const missing = (what: string): MusicPage => ({
+    status: 404,
+    head: { title: `No such ${what} · nixamp music`, description: `Nothing by that name is on nixamp music.`, type: "website", noindex: true },
+    body: `<h1>No such ${escape(what)}</h1><p><a href="/music">Every artist on nixamp music</a></p>`,
+  });
+
+  if (parts[0] === "me") {
+    return {
+      status: 200,
+      head: { title: "My music · nixamp", description: "The songs and albums you bought on nixamp, and the artists you follow.", type: "website", noindex: true },
+      body: "<h1>My music</h1><p>Sign in to see what you bought and who you follow.</p>",
+    };
+  }
+
+  if (parts[0] === "genre" && parts[1]) {
+    const genre = catalogue.genres.find((one) => slug(one.genre) === parts[1]);
+    if (!genre) return missing("genre");
+    const names = genre.artists.map((one) => one.name);
+    const lead = genre.artists[0];
+    return {
+      status: 200,
+      head: {
+        title: `${genre.genre} · nixamp music`,
+        description: clip(`${genre.genre} by AI artists on nixamp: ${names.join(", ")}. Listen free on the live station; follow the artists; buy the songs.`, 200),
+        type: "website",
+        ...(lead && pictureOf(lead) ? { image: pictureOf(lead)! } : {}),
+      },
+      body: `<h1>${escape(genre.genre)}</h1><ul>${genre.artists.map((one) => `<li><a href="${artistLink(one)}">${escape(one.name)}</a>${one.bio ? `: ${escape(clip(one.bio, 160))}` : ""}</li>`).join("")}</ul>`,
+    };
+  }
+
+  if (parts[0] === "artist" && parts[1] && parts[2]) {
+    const artist = artists.find((one) => one.server === parts[1] && one.key === parts[2]);
+    if (!artist) return missing("artist");
+    const image = pictureOf(artist);
+    const albums = artist.albums.filter((one) => one.songs.length > 0);
+    const members = artist.members ?? [];
+    return {
+      status: 200,
+      head: {
+        title: `${artist.name} · ${artist.genre} · nixamp music`,
+        description: clip(artist.bio || `${artist.name}, ${artist.genre} on nixamp: ${albums.length} album${albums.length === 1 ? "" : "s"}.`, 200),
+        type: "profile",
+        ...(image ? { image } : {}),
+        ld: {
+          "@context": "https://schema.org", "@type": "MusicGroup", name: artist.name, genre: artist.genre, url: at(artistLink(artist)),
+          ...(artist.bio ? { description: artist.bio } : {}),
+          ...(image ? { image: image.url } : {}),
+          ...(members.length ? { member: members.map((one) => ({ "@type": "Person", name: one.name, ...(one.role ? { roleName: one.role } : {}) })) } : {}),
+          album: albums.map((one) => ({ "@type": "MusicAlbum", name: one.title, url: at(`/music/album/${artist.server}/${artist.key}/${one.key}`), ...(one.year ? { datePublished: String(one.year) } : {}) })),
+          recordLabel: { "@type": "Organization", name: holder },
+        },
+      },
+      body: `<p><a href="/music">Music</a> / <a href="/music/genre/${slug(artist.genre)}">${escape(artist.genre)}</a></p><h1>${escape(artist.name)}</h1>`
+        + (artist.bio ? `<p>${escape(artist.bio)}</p>` : "")
+        + (members.length ? `<h2>Members</h2><ul>${members.map((one) => `<li>${escape(one.name)}${one.role ? `, ${escape(one.role)}` : ""}</li>`).join("")}</ul>` : "")
+        + (albums.length ? `<h2>Albums</h2><ul>${albums.map((one) => `<li><a href="/music/album/${artist.server}/${artist.key}/${one.key}">${escape(one.title)}</a>${one.year ? ` (${one.year})` : ""}</li>`).join("")}</ul>` : ""),
+    };
+  }
+
+  if (parts[0] === "album" && parts[1] && parts[2] && parts[3]) {
+    const artist = artists.find((one) => one.server === parts[1] && one.key === parts[2]);
+    const album = artist?.albums.find((one) => one.key === parts[3]);
+    if (!artist || !album) return missing("album");
+    const image = album.cover ? { url: file(artist.server, `${artist.key}/${album.key}/cover.jpg`), alt: `${album.title} by ${artist.name}, the cover` } : pictureOf(artist);
+    const url = at(`/music/album/${artist.server}/${artist.key}/${album.key}`);
+    return {
+      status: 200,
+      head: {
+        title: `${album.title} by ${artist.name} · nixamp music`,
+        description: clip(album.concept || `${album.title}, ${album.songs.length} songs by ${artist.name} (${artist.genre})${album.year ? `, ${album.year}` : ""}. Listen free on nixamp.`, 200),
+        type: "music.album",
+        ...(image ? { image } : {}),
+        extra: [
+          ["music:musician", at(artistLink(artist))],
+          ...(album.year ? [["music:release_date", String(album.year)] as [string, string]] : []),
+          ...album.songs.slice(0, 30).map((song) => ["music:song", `${url}#${song.n}`] as [string, string]),
+        ],
+        ld: {
+          "@context": "https://schema.org", "@type": "MusicAlbum", name: album.title, url,
+          byArtist: { "@type": "MusicGroup", name: artist.name, url: at(artistLink(artist)) },
+          genre: artist.genre, numTracks: album.songs.length,
+          ...(album.year ? { datePublished: String(album.year) } : {}),
+          ...(image ? { image: image.url } : {}),
+          ...(album.concept ? { description: album.concept } : {}),
+          recordLabel: { "@type": "Organization", name: holder },
+          track: album.songs.map((song) => ({ "@type": "MusicRecording", name: song.title, position: song.n, ...(song.seconds ? { duration: `PT${Math.floor(song.seconds / 60)}M${Math.round(song.seconds % 60)}S` } : {}) })),
+        },
+      },
+      body: `<p><a href="/music">Music</a> / <a href="${artistLink(artist)}">${escape(artist.name)}</a></p><h1>${escape(album.title)}</h1>`
+        + `<p>by <a href="${artistLink(artist)}">${escape(artist.name)}</a>${album.year ? ` · ${album.year}` : ""} · ${album.songs.length} songs</p>`
+        + (album.concept ? `<p>${escape(album.concept)}</p>` : "")
+        + `<ol>${album.songs.map((song) => `<li>${escape(song.title)}${song.seconds ? ` <span>${clock(song.seconds)}</span>` : ""}</li>`).join("")}</ol>`,
+    };
+  }
+
+  if (parts.length > 0) return missing("page");
+  const lead = artists.find((one) => pictureOf(one));
+  return {
+    status: 200,
+    head: {
+      title: "AI music, live and on demand · nixamp",
+      description: clip(`Original bands and artists, written and sung by AI and released by ${holder}: ${catalogue.genres.map((one) => one.genre).join(", ")}. Listen free; follow the artists; buy the songs.`, 200),
+      type: "website",
+      ...(lead ? { image: pictureOf(lead)! } : {}),
+    },
+    body: `<h1>AI music, live and on demand</h1>${catalogue.genres.map((genre) => `<h2><a href="/music/genre/${slug(genre.genre)}">${escape(genre.genre)}</a></h2><ul>${genre.artists.map((one) => `<li><a href="${artistLink(one)}">${escape(one.name)}</a></li>`).join("")}</ul>`).join("")}`,
+  };
+}
+
+/** The shell with a page's head and summary written in. */
+export function renderMusicPage(shell: string, page: MusicPage, url: string): string {
+  const { head } = page;
+  const meta: string[] = [
+    `<title>${escape(head.title)}</title>`,
+    `<meta name="description" content="${escape(head.description)}" />`,
+    `<link rel="canonical" href="${escape(url)}" />`,
+    ...(head.noindex ? [`<meta name="robots" content="noindex" />`] : []),
+    `<meta property="og:site_name" content="nixamp" />`,
+    `<meta property="og:title" content="${escape(head.title.replace(/ · nixamp( music)?$/, ""))}" />`,
+    `<meta property="og:description" content="${escape(head.description)}" />`,
+    `<meta property="og:type" content="${escape(head.type)}" />`,
+    `<meta property="og:url" content="${escape(url)}" />`,
+    ...(head.image ? [
+      `<meta property="og:image" content="${escape(head.image.url)}" />`,
+      `<meta property="og:image:alt" content="${escape(head.image.alt)}" />`,
+      `<meta name="twitter:card" content="summary_large_image" />`,
+      `<meta name="twitter:image" content="${escape(head.image.url)}" />`,
+    ] : [`<meta name="twitter:card" content="summary" />`]),
+    `<meta name="twitter:title" content="${escape(head.title)}" />`,
+    `<meta name="twitter:description" content="${escape(head.description)}" />`,
+    ...(head.extra ?? []).map(([property, content]) => `<meta property="${escape(property)}" content="${escape(content)}" />`),
+    ...(head.ld ? [`<script type="application/ld+json">${JSON.stringify(head.ld).replace(/</g, "\\u003c")}</script>`] : []),
+  ];
+  return shell
+    .replace(/<title>[^<]*<\/title>/, "")
+    .replace(/<meta name="description"[^>]*>/, "")
+    .replace("</head>", `    ${meta.join("\n    ")}\n  </head>`)
+    .replace(/(<main id="view"[^>]*>)(<\/main>)/, `$1${page.body}$2`);
+}