lightnet 4.9.0 → 4.10.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # lightnet
 
+## 4.10.0
+
+### Minor Changes
+
+- [#477](https://github.com/LightNetDev/LightNet/pull/477) [`67d9a6e`](https://github.com/LightNetDev/LightNet/commit/67d9a6eab378697f0baa80b70939b69c8fbdf237) - Add Open Graph and Twitter metadata to detail pages, with generated share images that preserve the full cover alongside the title and authors. Cards use cover-inspired backgrounds and the media type’s cover decoration. Sharp is now a peer dependency.
+
+### Patch Changes
+
+- [#477](https://github.com/LightNetDev/LightNet/pull/477) [`67d9a6e`](https://github.com/LightNetDev/LightNet/commit/67d9a6eab378697f0baa80b70939b69c8fbdf237) - Update dependencies.
+
 ## 4.9.0
 
 ### Minor Changes

package/package.json

@@ -3,7 +3,7 @@
   "description": "LightNet makes it easy to run your own digital media library.",
   "type": "module",
   "license": "MIT",
-  "version": "4.9.0",
+  "version": "4.10.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/LightNetDev/lightnet",
@@ -43,12 +43,14 @@
     "./pages/DetailsPageRoute.astro": "./src/pages/details-page/DetailsPageRoute.astro",
     "./api/internal/search.ts": "./src/pages/search-page/api/search.ts",
     "./api/versions.ts": "./src/api/versions.ts",
-    "./api/robots.ts": "./src/api/robots.ts"
+    "./api/robots.ts": "./src/api/robots.ts",
+    "./pages/detail-page/api/open-graph.ts": "./src/pages/details-page/api/open-graph.ts"
   },
   "peerDependencies": {
     "astro": "^6.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "sharp": "^0.34.5",
     "tailwindcss": ">=3.4.0 <4.0.0"
   },
   "dependencies": {
@@ -58,14 +60,14 @@
     "@iconify-json/mdi": "^1.2.3",
     "@iconify/tailwind": "^1.2.0",
     "@tailwindcss/typography": "^0.5.20",
-    "@tanstack/react-virtual": "^3.14.24",
+    "@tanstack/react-virtual": "^3.14.25",
     "autoprefixer": "^10.6.2",
     "embla-carousel": "^8.6.0",
     "embla-carousel-wheel-gestures": "^8.1.0",
     "fuse.js": "^7.5.0",
-    "i18next": "^26.6.0",
-    "lucide-react": "^1.66.0",
-    "marked": "^18.1.2",
+    "i18next": "^26.7.1",
+    "lucide-react": "^1.67.0",
+    "marked": "^18.1.3",
     "postcss": "^8.5.32",
     "postcss-load-config": "^6.0.1",
     "yaml": "^2.9.1"
@@ -76,7 +78,7 @@
     "@types/react": "^19.3.0",
     "astro": "^6.4.8",
     "typescript": "^6.0.3",
-    "vitest": "^5.0.5"
+    "vitest": "^5.1.0"
   },
   "engines": {
     "node": ">=22"

package/src/astro-integration/integration.ts

@@ -71,6 +71,12 @@ export function lightnet(lightnetConfig: LightnetConfig): AstroIntegration {
           prerender: true,
         })
 
+        injectRoute({
+          pattern: "/[locale]/media/[mediaId]/open-graph.png",
+          entrypoint: "lightnet/pages/detail-page/api/open-graph.ts",
+          prerender: true,
+        })
+
         injectRoute({
           pattern: "/api/internal/search.json",
           entrypoint: "lightnet/api/internal/search.ts",

package/src/pages/details-page/AudioDetailsPage.astro

@@ -6,25 +6,15 @@ import DetailsPage from "./components/DetailsPage.astro"
 import MainDetailsSection from "./components/MainDetailsSection.astro"
 import MediaCollectionsSection from "./components/MediaCollectionsSection.astro"
 import MoreDetailsSection from "./components/MoreDetailsSection.astro"
-import { getDetailsPageJsonLd } from "./utils/get-details-page-json-ld"
 
 export type Props = {
   mediaId: string
 }
 
 const { mediaId } = Astro.props
-const { defaultLocale, tContentField } = Astro.locals.i18n
-
-const jsonLd = await getDetailsPageJsonLd({
-  mediaId,
-  layout: "audio",
-  site: Astro.site,
-  defaultLocale,
-  tContentField,
-})
 ---
 
-<DetailsPage mediaId={mediaId} jsonLd={jsonLd}>
+<DetailsPage mediaId={mediaId} fallbackSchemaType="AudioObject">
   <MainDetailsSection imageSize="md" mediaId={mediaId} />
   <AudioPanel mediaId={mediaId} className="mt-10" />
   <DescriptionSection mediaId={mediaId} />

package/src/pages/details-page/DefaultDetailsPage.astro

@@ -6,24 +6,14 @@ import OpenButton from "./components/main-details/OpenButton.astro"
 import MainDetailsSection from "./components/MainDetailsSection.astro"
 import MediaCollectionsSection from "./components/MediaCollectionsSection.astro"
 import MoreDetailsSection from "./components/MoreDetailsSection.astro"
-import { getDetailsPageJsonLd } from "./utils/get-details-page-json-ld"
 
 export type Props = {
   mediaId: string
 }
 const { mediaId } = Astro.props
-const { defaultLocale, tContentField } = Astro.locals.i18n
-
-const jsonLd = await getDetailsPageJsonLd({
-  mediaId,
-  layout: "default",
-  site: Astro.site,
-  defaultLocale,
-  tContentField,
-})
 ---
 
-<DetailsPage mediaId={mediaId} jsonLd={jsonLd}>
+<DetailsPage mediaId={mediaId}>
   <MainDetailsSection mediaId={mediaId}>
     <OpenButton className="mt-8" mediaId={mediaId} />
   </MainDetailsSection>

package/src/pages/details-page/VideoDetailsPage.astro

@@ -5,25 +5,15 @@ import DetailsPage from "./components/DetailsPage.astro"
 import MediaCollectionsSection from "./components/MediaCollectionsSection.astro"
 import MoreDetailsSection from "./components/MoreDetailsSection.astro"
 import VideoDetailsSection from "./components/VideoDetailsSection.astro"
-import { getDetailsPageJsonLd } from "./utils/get-details-page-json-ld"
 
 export type Props = {
   mediaId: string
 }
 
 const { mediaId } = Astro.props
-const { defaultLocale, tContentField } = Astro.locals.i18n
-
-const jsonLd = await getDetailsPageJsonLd({
-  mediaId,
-  layout: "video",
-  site: Astro.site,
-  defaultLocale,
-  tContentField,
-})
 ---
 
-<DetailsPage mediaId={mediaId} jsonLd={jsonLd}>
+<DetailsPage mediaId={mediaId} fallbackSchemaType="VideoObject">
   <VideoDetailsSection mediaId={mediaId} />
   <DescriptionSection mediaId={mediaId} />
   <ContentSection mediaId={mediaId} />

package/src/pages/details-page/api/open-graph.ts

@@ -0,0 +1,41 @@
+import { readFile } from "node:fs/promises"
+
+import type { APIRoute, GetStaticPaths } from "astro"
+import { getCollection, getEntry } from "astro:content"
+import config from "virtual:lightnet/config"
+
+import { getMediaItem } from "../../../content/get-media-items"
+import { getMediaType } from "../../../content/get-media-types"
+import { createOpenGraphImage } from "../utils/create-open-graph-image"
+
+export const getStaticPaths: GetStaticPaths = async () => {
+  const items = await getCollection("media")
+  return config.locales.flatMap((locale) =>
+    items.map(({ id: mediaId }) => ({ params: { locale, mediaId } })),
+  )
+}
+
+export const GET: APIRoute = async ({ params, locals }) => {
+  const item = await getMediaItem(params.mediaId!)
+  const mediaType = await getMediaType(item.data.type.id)
+  // Read the original Astro image metadata: schema validation strips its
+  // non-enumerable fsPath, and optimized assets are generated after prerendering.
+  const entry = await getEntry("media", params.mediaId!)
+  const imagePath: unknown = Reflect.get(entry!.data.image, "fsPath")
+  if (typeof imagePath !== "string") {
+    throw new Error(
+      `Cannot resolve the cover image for media item "${item.id}"`,
+    )
+  }
+  const { direction } = locals.i18n
+  const png = await createOpenGraphImage({
+    cover: await readFile(imagePath),
+    coverImageStyle: mediaType.data.coverImageStyle,
+    title: item.data.title,
+    authors: item.data.authors,
+    direction,
+  })
+  return new Response(new Uint8Array(png), {
+    headers: { "Content-Type": "image/png" },
+  })
+}

package/src/pages/details-page/components/DetailsPage.astro

@@ -1,30 +1,58 @@
 ---
+import config from "virtual:lightnet/config"
+
 import { getMediaItem } from "../../../content/get-media-items"
 import Page from "../../../layouts/Page.astro"
 import { markdownToText } from "../../../utils/markdown"
 import { detailsPagePath } from "../../../utils/paths"
+import { getDetailsPageJsonLd } from "../utils/get-details-page-json-ld"
 
 type Props = {
   mediaId: string
-  /** Structured data to include in the page head as JSON-LD. */
-  jsonLd?: Record<string, unknown>
+  /** Schema.org type used when the media type does not specify one. */
+  fallbackSchemaType?: string
 }
 
-const { mediaId: id, jsonLd } = Astro.props
+const { mediaId: id, fallbackSchemaType = "CreativeWork" } = Astro.props
+const { defaultLocale, currentLocale, tContentField, tConfigField } =
+  Astro.locals.i18n
 const mediaItem = (await getMediaItem(id)).data
+const description = markdownToText(mediaItem.description)
+const shareUrl = new URL(detailsPagePath(currentLocale, { id }), Astro.site)
+const shareImage = new URL("open-graph.png", shareUrl)
+const jsonLd = await getDetailsPageJsonLd({
+  mediaId: id,
+  fallbackSchemaType,
+  site: Astro.site,
+  defaultLocale,
+  tContentField,
+})
 ---
 
 <Page
   title={mediaItem.title}
-  description={markdownToText(mediaItem.description)}
-  canonicalUrl={
-    new URL(
-      detailsPagePath(Astro.locals.i18n.defaultLocale, { id }),
-      Astro.site,
-    )
-  }
+  description={description}
+  canonicalUrl={new URL(detailsPagePath(defaultLocale, { id }), Astro.site)}
 >
   <Fragment slot="head">
+    <meta property="og:type" content="website" />
+    <meta property="og:title" content={mediaItem.title} />
+    {description && <meta property="og:description" content={description} />}
+    <meta
+      property="og:site_name"
+      content={tConfigField(config.title, config)}
+    />
+    <meta property="og:url" content={shareUrl.href} />
+    <meta property="og:image" content={shareImage.href} />
+    <meta property="og:image:type" content="image/png" />
+    <meta property="og:image:width" content="1200" />
+    <meta property="og:image:height" content="630" />
+    <meta property="og:image:alt" content={mediaItem.title} />
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content={mediaItem.title} />
+    {description && <meta name="twitter:description" content={description} />}
+    <meta name="twitter:image" content={shareImage.href} />
+    <meta name="twitter:image:alt" content={mediaItem.title} />
     {jsonLd && (
       <script
         type="application/ld+json"

package/src/pages/details-page/utils/create-media-item-json-ld.ts

@@ -23,11 +23,9 @@ const FILE_FORMATS: Record<string, { type: string; mime: string }> = {
   txt: { type: "MediaObject", mime: "text/plain" },
 }
 
-export type DetailsPageLayout = "default" | "audio" | "video"
-
 export function createMediaItemJsonLd({
   item,
-  layout,
+  fallbackSchemaType = "CreativeWork",
   schemaType,
   canonicalUrl,
   imageUrl,
@@ -35,16 +33,17 @@ export function createMediaItemJsonLd({
   contentLabels = [],
 }: {
   item: MediaItemEntry["data"]
-  layout: DetailsPageLayout
+  fallbackSchemaType?: string
   schemaType?: MediaTypeEntry["data"]["schemaType"]
   canonicalUrl: URL
   imageUrl: string
   categoryNames?: string[]
   contentLabels?: (string | undefined)[]
 }): Record<string, unknown> {
+  const resolvedSchemaType = schemaType ?? fallbackSchemaType
   const base = {
     "@context": "https://schema.org",
-    "@type": schemaType ?? "CreativeWork",
+    "@type": resolvedSchemaType,
     "@id": `${canonicalUrl.href}#work`,
     url: canonicalUrl.href,
     name: item.title,
@@ -87,7 +86,10 @@ export function createMediaItemJsonLd({
   })
 
   const encodings = media.filter((entry) => entry !== undefined)
-  if (schemaType === "SoftwareApplication" || schemaType === "WebPage") {
+  if (
+    resolvedSchemaType === "SoftwareApplication" ||
+    resolvedSchemaType === "WebPage"
+  ) {
     const primary = item.content[0]
     const resourceUrl =
       primary?.type === "link"
@@ -102,55 +104,35 @@ export function createMediaItemJsonLd({
   }
 
   if (
-    schemaType === "AudioObject" ||
-    schemaType === "VideoObject" ||
-    schemaType === "ImageObject"
+    resolvedSchemaType === "AudioObject" ||
+    resolvedSchemaType === "VideoObject" ||
+    resolvedSchemaType === "ImageObject"
   ) {
-    const matching = encodings.filter((entry) => entry["@type"] === schemaType)
-    if (schemaType === "AudioObject" && matching.length > 1) {
+    const matching = encodings.filter(
+      (entry) => entry["@type"] === resolvedSchemaType,
+    )
+    if (resolvedSchemaType === "AudioObject" && matching.length > 1) {
       return {
         ...base,
         hasPart: matching,
-        encoding: encodings.filter((entry) => entry["@type"] !== schemaType),
+        encoding: encodings.filter(
+          (entry) => entry["@type"] !== resolvedSchemaType,
+        ),
       }
     }
-    const primary = media[0]?.["@type"] === schemaType ? media[0] : undefined
+    const primary =
+      media[0]?.["@type"] === resolvedSchemaType ? media[0] : undefined
     const alternatives = encodings.filter((entry) => entry !== primary)
     return {
       ...primary,
       ...base,
-      ...(schemaType === "VideoObject" ? { thumbnailUrl: imageUrl } : {}),
+      ...(resolvedSchemaType === "VideoObject"
+        ? { thumbnailUrl: imageUrl }
+        : {}),
       encoding: alternatives.length ? alternatives : undefined,
     }
   }
 
-  if (
-    !schemaType &&
-    layout === "video" &&
-    media[0]?.["@type"] === "VideoObject"
-  ) {
-    return {
-      ...media[0],
-      ...base,
-      "@type": "VideoObject",
-      thumbnailUrl: imageUrl,
-    }
-  }
-
-  if (layout === "audio") {
-    const tracks = encodings.filter((entry) => entry["@type"] === "AudioObject")
-    if (!schemaType && tracks.length === 1 && item.content.length === 1) {
-      return { ...tracks[0], ...base, "@type": "AudioObject" }
-    }
-    if (tracks.length && item.content.length > 1) {
-      return {
-        ...base,
-        hasPart: tracks,
-        encoding: encodings.filter((entry) => entry["@type"] !== "AudioObject"),
-      }
-    }
-  }
-
   return { ...base, encoding: encodings.length ? encodings : undefined }
 }
 

package/src/pages/details-page/utils/create-open-graph-image.ts

@@ -0,0 +1,186 @@
+import sharp, { type OverlayOptions } from "sharp"
+
+import type { MediaTypeEntry } from "../../../content/schema/media-type"
+
+export const OPEN_GRAPH_WIDTH = 1200
+export const OPEN_GRAPH_HEIGHT = 630
+
+// Text is Pango markup. Escape user content before passing it to the renderer.
+function escapeMarkup(text: string) {
+  return text.replace(
+    /[&<>"']/g,
+    (character) =>
+      ({
+        "&": "&amp;",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&apos;",
+      })[character]!,
+  )
+}
+
+async function renderText(
+  value: string,
+  {
+    width,
+    height,
+    size,
+    color,
+    bold = false,
+    rtl = false,
+  }: {
+    width: number
+    height: number
+    size: number
+    color: string
+    bold?: boolean
+    rtl?: boolean
+  },
+) {
+  let fontSize = size
+  // Measure the rendered text and reduce the font until every line fits.
+  // Pango handles Unicode shaping, bidi text, and wrapping long words.
+  while (true) {
+    const result = await sharp({
+      text: {
+        text: `<span foreground="${color}">${escapeMarkup(value)}</span>`,
+        font: `sans ${bold ? "bold " : ""}${fontSize}`,
+        width,
+        wrap: "word-char",
+        align: rtl ? "right" : "left",
+        rgba: true,
+      },
+    })
+      .png()
+      .toBuffer({ resolveWithObject: true })
+    if (result.info.height <= height) return result
+    fontSize *= 0.9
+  }
+}
+
+export async function createOpenGraphImage({
+  cover,
+  title,
+  authors = [],
+  direction = "ltr",
+  coverImageStyle = "default",
+}: {
+  cover: Buffer
+  title: string
+  authors?: string[] | null
+  direction?: "ltr" | "rtl"
+  coverImageStyle?: MediaTypeEntry["data"]["coverImageStyle"]
+}) {
+  const rtl = direction === "rtl"
+  const textStart = rtl ? 64 : 560
+  const coverImage = await sharp(cover)
+    .autoOrient()
+    .resize(432, 502, { fit: "inside" })
+    .png()
+    .toBuffer({ resolveWithObject: true })
+  const { dominant } = await sharp(coverImage.data).stats()
+  const { width: coverWidth, height: coverHeight } = coverImage.info
+  const cornerRadius = coverImageStyle === "book" ? 2 : 6
+  const decorations: OverlayOptions[] = []
+  if (coverImageStyle === "book") {
+    decorations.push({
+      input: Buffer.from(`<svg width="${coverWidth}" height="${coverHeight}">
+        <defs>
+          <linearGradient id="spine" x1="${rtl ? 1 : 0}" x2="${rtl ? 0 : 1}">
+            <stop stop-color="#6b7280" stop-opacity="0.2"/>
+            <stop offset="1" stop-color="#6b7280" stop-opacity="0"/>
+          </linearGradient>
+        </defs>
+        <rect x="${coverWidth * (rtl ? 0.97 : 0.01)}" width="${coverWidth * 0.02}" height="100%" fill="url(#spine)"/>
+      </svg>`),
+    })
+  }
+  decorations.push({
+    input: Buffer.from(`<svg width="${coverWidth}" height="${coverHeight}">
+      <rect width="100%" height="100%" rx="${cornerRadius}" fill="white"/>
+    </svg>`),
+    blend: "dest-in",
+  })
+  const decoratedCover = await sharp(coverImage.data)
+    .ensureAlpha()
+    .composite(decorations)
+    .png()
+    .toBuffer()
+  const tint = `rgb(${[dominant.r, dominant.g, dominant.b]
+    .map((channel) => Math.round(250 * 0.68 + channel * 0.32))
+    .join(",")})`
+  const coverLeft =
+    (rtl ? 704 : 64) + Math.floor((432 - coverImage.info.width) / 2)
+  const coverTop = 64 + Math.floor((502 - coverImage.info.height) / 2)
+  const layers: OverlayOptions[] = [
+    {
+      input: decoratedCover,
+      left: coverLeft,
+      top: coverTop,
+    },
+  ]
+  const textLayers: OverlayOptions[] = []
+  const addText = async (
+    value: string,
+    top: number,
+    height: number,
+    size: number,
+    color: string,
+    bold = false,
+  ) => {
+    if (!value.trim()) return 0
+    const text = await renderText(value, {
+      width: 576,
+      height,
+      size,
+      color,
+      bold,
+      rtl,
+    })
+    textLayers.push({
+      input: text.data,
+      left: textStart + (rtl ? 576 - text.info.width : 0),
+      top,
+    })
+    return text.info.height
+  }
+
+  const titleHeight = await addText(title, 0, 280, 64, "#111827", true)
+  const authorsHeight = await addText(
+    authors?.join(", ") ?? "",
+    titleHeight + 24,
+    84,
+    32,
+    "#4b5563",
+  )
+  const contentHeight = titleHeight + (authorsHeight ? 24 + authorsHeight : 0)
+  const textTop = Math.round((OPEN_GRAPH_HEIGHT - contentHeight) / 2)
+  layers.push(
+    ...textLayers.map((layer) => ({
+      ...layer,
+      top: textTop + (layer.top ?? 0),
+    })),
+  )
+
+  return sharp(
+    Buffer.from(`<svg width="${OPEN_GRAPH_WIDTH}" height="${OPEN_GRAPH_HEIGHT}">
+    <defs>
+      <linearGradient id="background" x1="0" y1="0" x2="1" y2="1">
+        <stop stop-color="${rtl ? "#fcfcfd" : tint}"/>
+        <stop offset="1" stop-color="${rtl ? tint : "#fcfcfd"}"/>
+      </linearGradient>
+      <filter id="shadow" x="-50%" y="-50%" width="200%" height="200%">
+        <feGaussianBlur stdDeviation="16"/>
+      </filter>
+    </defs>
+    <rect width="100%" height="100%" fill="url(#background)"/>
+    <rect x="${coverLeft}" y="${coverTop + 12}" width="${coverImage.info.width}" height="${coverImage.info.height}" rx="${cornerRadius}"
+      fill="#0f172a" opacity="0.18" filter="url(#shadow)"/>
+  </svg>`),
+  )
+    .flatten({ background: "#fafafa" })
+    .composite(layers)
+    .png()
+    .toBuffer()
+}

package/src/pages/details-page/utils/get-details-page-json-ld.ts

@@ -5,18 +5,17 @@ import { getMediaItem } from "../../../content/get-media-items"
 import { getMediaType } from "../../../content/get-media-types"
 import type { TranslateContentFieldFn } from "../../../i18n/translate-map"
 import { detailsPagePath } from "../../../utils/paths"
-import type { DetailsPageLayout } from "./create-media-item-json-ld"
 import { createMediaItemJsonLd } from "./create-media-item-json-ld"
 
 export async function getDetailsPageJsonLd({
   mediaId,
-  layout,
+  fallbackSchemaType,
   site,
   defaultLocale,
   tContentField,
 }: {
   mediaId: string
-  layout: DetailsPageLayout
+  fallbackSchemaType: string
   site: URL | undefined
   defaultLocale: string
   tContentField: TranslateContentFieldFn
@@ -36,7 +35,7 @@ export async function getDetailsPageJsonLd({
 
   return createMediaItemJsonLd({
     item: item.data,
-    layout,
+    fallbackSchemaType,
     schemaType: mediaType.data.schemaType,
     canonicalUrl,
     imageUrl: new URL(image.src, site).href,