lightnet 4.9.0 → 4.11.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # lightnet
 
+## 4.11.0
+
+### Minor Changes
+
+- [#479](https://github.com/LightNetDev/LightNet/pull/479) [`d152514`](https://github.com/LightNetDev/LightNet/commit/d152514a2a637cdb6f6fb8ad8f83702a5e7e246a) - Add `disableOpenGraphImages` to skip generating Open Graph images and use media cover images for Open Graph and Twitter previews instead. Generation remains enabled by default.
+
+- [#479](https://github.com/LightNetDev/LightNet/pull/479) [`d152514`](https://github.com/LightNetDev/LightNet/commit/d152514a2a637cdb6f6fb8ad8f83702a5e7e246a) - Add cover-colored gradients to the opening section of details pages, with softer cover shadows and clearer primary actions. Share color extraction with Open Graph images, persist calculated colors in Astro's cache directory across builds, and use CSS custom properties to keep gradient styles independent of the number of covers.
+
+### Patch Changes
+
+- [#479](https://github.com/LightNetDev/LightNet/pull/479) [`d152514`](https://github.com/LightNetDev/LightNet/commit/d152514a2a637cdb6f6fb8ad8f83702a5e7e246a) - Use color tint for HighlightSection coloring.
+
+- [#479](https://github.com/LightNetDev/LightNet/pull/479) [`d152514`](https://github.com/LightNetDev/LightNet/commit/d152514a2a637cdb6f6fb8ad8f83702a5e7e246a) - Add transparent effect to headerbar.
+
+- [#479](https://github.com/LightNetDev/LightNet/pull/479) [`d152514`](https://github.com/LightNetDev/LightNet/commit/d152514a2a637cdb6f6fb8ad8f83702a5e7e246a) - Add performance improvements for open-graph image generation.
+
+## 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/exports/details-page.ts

@@ -4,6 +4,7 @@
  */
 export { default as ContentSection } from "../src/pages/details-page/components/ContentSection.astro"
 export { default as DescriptionSection } from "../src/pages/details-page/components/DescriptionSection.astro"
+export { default as DetailsHero } from "../src/pages/details-page/components/DetailsHero.astro"
 export { default as DetailsPage } from "../src/pages/details-page/components/DetailsPage.astro"
 export { default as OpenButton } from "../src/pages/details-page/components/main-details/OpenButton.astro"
 export { default as ShareButton } from "../src/pages/details-page/components/main-details/ShareButton.astro"

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.11.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/config.ts

@@ -114,6 +114,11 @@ export const configSchema = z.object({
    * not add any page of this media library to their search results.
    */
   disallowSearchIndexing: z.boolean().optional(),
+  /**
+   * Disable Open Graph image generation and use media cover images for
+   * Open Graph and Twitter previews instead. Generation is enabled by default.
+   */
+  disableOpenGraphImages: z.boolean().default(false),
   /**
    * Link to manifest file within public/ folder
    */

package/src/astro-integration/integration.ts

@@ -71,6 +71,14 @@ export function lightnet(lightnetConfig: LightnetConfig): AstroIntegration {
           prerender: true,
         })
 
+        if (!config.disableOpenGraphImages) {
+          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/components/HighlightSection.astro

@@ -1,8 +1,11 @@
 ---
 import type { ImageMetadata } from "astro"
 import { Image } from "astro:assets"
+import { cacheDir } from "astro:config/server"
 import { ArrowRightIcon } from "lucide-react"
 
+import { getImageTint } from "../utils/get-image-tint"
+
 interface Props {
   image: ImageMetadata
   id?: string
@@ -16,14 +19,30 @@ interface Props {
 
 const { image, id, title, text, link, className, titleClass, textClass } =
   Astro.props
+let tint = "#e5e7eb"
+try {
+  tint = await getImageTint(image, new URL(cacheDir))
+} catch (error) {
+  console.warn("[lightnet] Cannot extract highlight image color:", error)
+}
+const tintChannels = tint.startsWith("rgb(")
+  ? tint.slice(4, -1).split(",").map(Number)
+  : [229, 231, 235]
+const darkTint = (factor: number) =>
+  `rgb(${tintChannels.map((channel) => Math.round(channel * factor)).join(",")})`
 const iconDirectionClass =
   Astro.locals.i18n.direction === "rtl" ? "scale-x-[-1]" : ""
 ---
 
 <section
-  class="mt-24 w-full bg-gray-200 md:mt-28"
+  class="mt-24 w-full bg-[var(--image-tint)] text-gray-900 md:mt-28"
   class:list={[className]}
   id={id}
+  style={{
+    "--image-tint": tint,
+    "--button-tint": darkTint(0.12),
+    "--button-hover-tint": darkTint(0.08),
+  }}
 >
   <div class="flex flex-col overflow-hidden md:flex-row">
     <Image
@@ -49,7 +68,7 @@ const iconDirectionClass =
       )}
       {link && (
         <a
-          class="inline-flex items-center justify-center gap-2 rounded-2xl bg-primary px-6 py-3 text-sm font-bold text-gray-50 shadow-sm hover:bg-primary/85 hover:text-gray-100"
+          class="inline-flex items-center justify-center gap-2 rounded-2xl bg-[var(--button-tint)] px-6 py-3 text-sm font-bold text-gray-50 shadow-sm transition-colors hover:bg-[var(--button-hover-tint)] hover:text-gray-100"
           href={link.href}
         >
           {link.text}
@@ -60,3 +79,13 @@ const iconDirectionClass =
     </div>
   </div>
 </section>
+
+<style>
+  section {
+    background-image: linear-gradient(
+      to bottom,
+      rgb(255 255 255 / 25%),
+      transparent
+    );
+  }
+</style>

package/src/layouts/components/header/Header.astro

@@ -3,7 +3,7 @@ import PageNavigation from "./PageNavigation.astro"
 import PageTitle from "./PageTitle.astro"
 ---
 
-<header class="fixed top-0 z-50 h-14 w-full bg-white shadow-md sm:h-20">
+<header class="fixed top-0 z-50 h-14 w-full border-b border-black/5 before:pointer-events-none before:absolute before:inset-0 before:-z-10 before:bg-white/85 before:backdrop-blur-lg sm:h-20">
   <div class="mx-auto flex h-full max-w-screen-xl justify-between px-4 md:px-8">
     <PageTitle />
     <PageNavigation />

package/src/layouts/components/header/Menu.astro

@@ -21,7 +21,7 @@ const { label, disabled } = Astro.props
     data-menu-panel
     aria-hidden="true"
     inert
-    class="pointer-events-none absolute end-3 top-full mt-px flex w-48 origin-top scale-y-90 flex-col overflow-hidden rounded-b-md bg-white py-3 opacity-0 shadow-lg transition-all duration-100 ease-out motion-reduce:transform-none motion-reduce:transition-none"
+    class="pointer-events-none absolute end-3 top-full mt-px flex w-48 origin-top scale-y-90 flex-col overflow-hidden rounded-b-md bg-white/85 py-3 opacity-0 shadow-lg backdrop-blur-lg transition-all duration-100 ease-out motion-reduce:transform-none motion-reduce:transition-none"
   >
     <slot />
   </ul>

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

@@ -2,31 +2,24 @@
 import AudioPanel from "./components/AudioPanel.astro"
 import ContentSection from "./components/ContentSection.astro"
 import DescriptionSection from "./components/DescriptionSection.astro"
+import DetailsHero from "./components/DetailsHero.astro"
 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}>
-  <MainDetailsSection imageSize="md" mediaId={mediaId} />
-  <AudioPanel mediaId={mediaId} className="mt-10" />
+<DetailsPage mediaId={mediaId} fallbackSchemaType="AudioObject">
+  <DetailsHero mediaId={mediaId}>
+    <MainDetailsSection imageSize="md" mediaId={mediaId} />
+    <AudioPanel mediaId={mediaId} className="mt-10" />
+  </DetailsHero>
   <DescriptionSection mediaId={mediaId} />
   <ContentSection mediaId={mediaId} minimumItems={1} />
   <MediaCollectionsSection mediaId={mediaId} />

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

@@ -1,32 +1,25 @@
 ---
 import ContentSection from "./components/ContentSection.astro"
 import DescriptionSection from "./components/DescriptionSection.astro"
+import DetailsHero from "./components/DetailsHero.astro"
 import DetailsPage from "./components/DetailsPage.astro"
 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}>
-  <MainDetailsSection mediaId={mediaId}>
-    <OpenButton className="mt-8" mediaId={mediaId} />
-  </MainDetailsSection>
+<DetailsPage mediaId={mediaId}>
+  <DetailsHero mediaId={mediaId}>
+    <MainDetailsSection mediaId={mediaId}>
+      <OpenButton className="mt-6" mediaId={mediaId} />
+    </MainDetailsSection>
+  </DetailsHero>
   <DescriptionSection mediaId={mediaId} />
   <ContentSection mediaId={mediaId} />
   <MediaCollectionsSection mediaId={mediaId} />

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

@@ -1,30 +1,23 @@
 ---
 import ContentSection from "./components/ContentSection.astro"
 import DescriptionSection from "./components/DescriptionSection.astro"
+import DetailsHero from "./components/DetailsHero.astro"
 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}>
-  <VideoDetailsSection mediaId={mediaId} />
+<DetailsPage mediaId={mediaId} fallbackSchemaType="VideoObject">
+  <DetailsHero mediaId={mediaId}>
+    <VideoDetailsSection mediaId={mediaId} />
+  </DetailsHero>
   <DescriptionSection mediaId={mediaId} />
   <ContentSection mediaId={mediaId} />
   <MediaCollectionsSection mediaId={mediaId} />

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

@@ -0,0 +1,35 @@
+import type { APIRoute, GetStaticPaths } from "astro"
+import { cacheDir } from "astro:config/server"
+import { getCollection } from "astro:content"
+import config from "virtual:lightnet/config"
+
+import { getMediaItem } from "../../../content/get-media-items"
+import { getMediaType } from "../../../content/get-media-types"
+import { getCachedOpenGraphImage } from "../utils/get-cached-open-graph-image"
+import { getMediaCover } from "../utils/get-media-cover"
+
+export const getStaticPaths: GetStaticPaths = async () => {
+  const items = await getCollection("media")
+  return items.map(({ id: mediaId }) => ({
+    params: { locale: config.defaultLocale, mediaId },
+  }))
+}
+
+export const GET: APIRoute = async ({ params, locals }) => {
+  const item = await getMediaItem(params.mediaId!)
+  const mediaType = await getMediaType(item.data.type.id)
+  const { direction } = locals.i18n
+  const png = await getCachedOpenGraphImage(
+    {
+      cover: await getMediaCover(item.id),
+      coverImageStyle: mediaType.data.coverImageStyle,
+      title: item.data.title,
+      authors: item.data.authors,
+      direction,
+    },
+    new URL(cacheDir),
+  )
+  return new Response(new Uint8Array(png), {
+    headers: { "Content-Type": "image/png" },
+  })
+}

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

@@ -16,7 +16,12 @@ const isMp3 = audioExtension.endsWith(".mp3")
 ---
 
 {isMp3 ? (
-  <audio class="rounded-2xl" class:list={[className]} src={src} controls />
+  <audio
+    class="overflow-hidden rounded-2xl border border-gray-200"
+    class:list={[className]}
+    src={src}
+    controls
+  />
 ) : (
   <a
     class="group flex w-full items-center gap-4 rounded-2xl border border-gray-200 bg-white px-4 py-4 shadow-sm transition hover:border-gray-300 hover:bg-gray-50 focus:outline-none focus-visible:ring-2 focus-visible:ring-gray-900/70"
@@ -47,6 +52,11 @@ const isMp3 = audioExtension.endsWith(".mp3")
 )}
 
 <style>
+  audio::-webkit-media-controls-enclosure,
+  audio::-webkit-media-controls-panel {
+    background-color: #f9fafb;
+  }
+
   audio::-webkit-media-controls-enclosure {
     border-radius: 0;
   }

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

@@ -0,0 +1,50 @@
+---
+import { cacheDir } from "astro:config/server"
+
+import { getImageTint } from "../../../utils/get-image-tint"
+import { getMediaCover } from "../utils/get-media-cover"
+
+interface Props {
+  mediaId: string
+}
+
+const { direction } = Astro.locals.i18n
+let tint = "#fafafa"
+try {
+  tint = await getImageTint(
+    await getMediaCover(Astro.props.mediaId),
+    new URL(cacheDir),
+  )
+} catch (error) {
+  console.warn("[lightnet] Cannot extract details page cover color:", error)
+}
+---
+
+<div
+  class="details-hero"
+  style={{
+    "--cover-tint": tint,
+    "--hero-direction":
+      direction === "rtl" ? "to bottom left" : "to bottom right",
+  }}
+>
+  <slot />
+</div>
+
+<style>
+  .details-hero {
+    /* Extend the same gradient behind the fixed header. */
+    margin-block-start: -3.5rem;
+    padding-block: calc(2.5rem + 3.5rem) 3rem;
+    background:
+      linear-gradient(to bottom, transparent 40%, #f9fafb),
+      linear-gradient(var(--hero-direction), var(--cover-tint), #f9fafb 85%);
+  }
+
+  @media (min-width: 640px) {
+    .details-hero {
+      margin-block-start: -5rem;
+      padding-block: calc(4rem + 5rem) 4rem;
+    }
+  }
+</style>

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

@@ -1,30 +1,73 @@
 ---
+import { getImage } from "astro:assets"
+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 coverImage = config.disableOpenGraphImages
+  ? await getImage({ src: mediaItem.image, format: "png" })
+  : undefined
+const shareImage = coverImage
+  ? new URL(coverImage.src, Astro.site)
+  : new URL(
+      `${detailsPagePath(defaultLocale, { id })}open-graph.png`,
+      Astro.site,
+    )
+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={String(coverImage ? mediaItem.image.width : 1200)}
+    />
+    <meta
+      property="og:image:height"
+      content={String(coverImage ? mediaItem.image.height : 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/components/MainDetailsSection.astro

@@ -13,15 +13,15 @@ export type Props = {
 const { mediaId, imageSize } = Astro.props
 ---
 
-<div class="mx-auto mt-10 flex max-w-screen-md flex-col items-center gap-8 px-4 sm:mt-20 sm:flex-row sm:items-start sm:gap-14 md:px-8">
+<div class="mx-auto flex max-w-screen-md flex-col items-center gap-8 px-4 sm:flex-row sm:gap-14 md:px-8">
   <CoverImage size={imageSize} mediaId={mediaId} />
   <div class="flex w-full grow flex-col items-center sm:items-start">
     <Title className="text-center sm:text-start" mediaId={mediaId} />
     <Authors className="mt-2" mediaId={mediaId} />
-    <div class="mt-4 flex gap-6">
+    <slot />
+    <div class="mt-5 flex gap-6 text-sm text-gray-600">
       <ShareButton />
       <EditButton mediaId={mediaId} />
     </div>
-    <slot />
   </div>
 </div>

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

@@ -15,7 +15,7 @@ const { mediaId } = Astro.props
 const item = await getMediaItem(mediaId)
 ---
 
-<div class="mx-auto max-w-screen-md md:mt-8 md:px-8">
+<div class="mx-auto max-w-screen-md px-4 md:px-8">
   <VideoPlayer
     url={item.data.content[0].url!}
     title={item.data.title}
@@ -25,7 +25,7 @@ const item = await getMediaItem(mediaId)
 <div class="mx-auto mt-6 flex max-w-screen-md flex-col items-start px-4 md:mt-10 md:px-8">
   <Title mediaId={mediaId} />
   <Authors mediaId={mediaId} />
-  <div class="mt-4 flex gap-6">
+  <div class="mt-5 flex gap-6 text-sm text-gray-600">
     <ShareButton />
     <EditButton mediaId={mediaId} />
   </div>

package/src/pages/details-page/components/main-details/CoverImage.astro

@@ -27,7 +27,10 @@ const imageSizes = {
 }
 ---
 
-<CoverImageDecorator className="shrink-0" style={type.data.coverImageStyle}>
+<CoverImageDecorator
+  className="shrink-0 shadow-xl shadow-gray-900/10"
+  style={type.data.coverImageStyle}
+>
   <Image
     class:list={imageSizes[size].css}
     alt=""

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,198 @@
+import sharp, { type OverlayOptions } from "sharp"
+
+import type { MediaTypeEntry } from "../../../content/schema/media-type"
+import { getImageTint } from "../../../utils/get-image-tint"
+
+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,
+    maxSize,
+    color,
+    bold = false,
+    rtl = false,
+  }: {
+    width: number
+    height: number
+    maxSize: number
+    color: string
+    bold?: boolean
+    rtl?: boolean
+  },
+) {
+  // Estimate the occupied area using average glyph width (0.55 em) and
+  // line height (1.2 em). Count Unicode code points rather than UTF-16 units.
+  const size = Math.max(
+    1,
+    Math.min(
+      maxSize,
+      Math.floor(
+        Math.sqrt((width * height) / ([...value].length * 0.55 * 1.2)),
+      ),
+    ),
+  )
+  const render = (fit = false) =>
+    sharp({
+      text: {
+        text: `<span foreground="${color}">${escapeMarkup(value)}</span>`,
+        font: `sans ${bold ? "bold " : ""}${size}`,
+        width,
+        ...(fit ? { height } : {}),
+        wrap: "word-char",
+        align: rtl ? "right" : "left",
+        rgba: true,
+      },
+    })
+      .raw()
+      .toBuffer({ resolveWithObject: true })
+  const result = await render()
+  // Wide glyphs, shaping, and explicit line breaks can exceed the estimate.
+  return result.info.height <= height ? result : render(true)
+}
+
+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"]
+  },
+  cacheDir?: URL,
+) {
+  const rtl = direction === "rtl"
+  const textStart = rtl ? 64 : 560
+  const coverImage = await sharp(cover)
+    .autoOrient()
+    .resize(432, 502, { fit: "inside" })
+    .ensureAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true })
+  const tint = await getImageTint(cover, cacheDir)
+  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, { raw: coverImage.info })
+    .composite(decorations)
+    .raw()
+    .toBuffer({ resolveWithObject: true })
+  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.data,
+      raw: decoratedCover.info,
+      left: coverLeft,
+      top: coverTop,
+    },
+  ]
+  const textLayers: OverlayOptions[] = []
+  const addText = async (
+    value: string,
+    top: number,
+    height: number,
+    maxSize: number,
+    color: string,
+    bold = false,
+  ) => {
+    if (!value.trim()) return 0
+    const text = await renderText(value, {
+      width: 576,
+      height,
+      maxSize,
+      color,
+      bold,
+      rtl,
+    })
+    textLayers.push({
+      input: text.data,
+      raw: text.info,
+      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-cached-open-graph-image.ts

@@ -0,0 +1,52 @@
+import { createHash, randomUUID } from "node:crypto"
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises"
+
+import sharp from "sharp"
+
+import { createOpenGraphImage } from "./create-open-graph-image"
+
+// Bump when changing the renderer, layout, or fonts to invalidate old images.
+const RENDERER_VERSION = 345
+
+export async function getCachedOpenGraphImage(
+  input: Parameters<typeof createOpenGraphImage>[0],
+  cacheDir: URL,
+) {
+  const key = createHash("sha256")
+    .update(
+      JSON.stringify({
+        version: RENDERER_VERSION,
+        dependencies: sharp.versions,
+        title: input.title,
+        authors: input.authors ?? [],
+        direction: input.direction ?? "ltr",
+        coverImageStyle: input.coverImageStyle ?? "default",
+      }),
+    )
+    .update(input.cover)
+    .digest("hex")
+  const directory = new URL("lightnet/open-graph/", cacheDir)
+  const imagePath = new URL(`${key}.png`, directory)
+
+  try {
+    return await readFile(imagePath)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      console.warn("[lightnet] Cannot read Open Graph image cache:", error)
+      return createOpenGraphImage(input, cacheDir)
+    }
+  }
+
+  const png = await createOpenGraphImage(input, cacheDir)
+  const temporaryPath = new URL(`${key}.${randomUUID()}.tmp`, directory)
+  try {
+    await mkdir(directory, { recursive: true })
+    await writeFile(temporaryPath, png, { flag: "wx" })
+    await rename(temporaryPath, imagePath)
+  } catch (error) {
+    console.warn("[lightnet] Cannot write Open Graph image cache:", error)
+  } finally {
+    await rm(temporaryPath, { force: true }).catch(() => undefined)
+  }
+  return png
+}

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,

package/src/pages/details-page/utils/get-media-cover.ts

@@ -0,0 +1,16 @@
+import { readFile } from "node:fs/promises"
+
+import { getEntry } from "astro:content"
+
+export async function getMediaCover(mediaId: string) {
+  // Schema validation strips fsPath; optimized assets are not available yet
+  // during prerendering. Read the original Astro image metadata instead.
+  const entry = await getEntry("media", mediaId)
+  const imagePath: unknown = entry && Reflect.get(entry.data.image, "fsPath")
+  if (typeof imagePath !== "string") {
+    throw new Error(
+      `Cannot resolve the cover image for media item "${mediaId}"`,
+    )
+  }
+  return readFile(imagePath)
+}

package/src/utils/get-image-tint.ts

@@ -0,0 +1,144 @@
+import { createHash, randomUUID } from "node:crypto"
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises"
+
+import type { ImageMetadata } from "astro"
+import sharp from "sharp"
+
+// Bound the cache for long-running dev/SSR servers. Locales share the same tint.
+const tints = new Map<string, Promise<string>>()
+// Bump when changing the extraction or tint formula.
+const TINT_VERSION = 2
+
+function getChromaticColor(pixels: Buffer): number[] | undefined {
+  // Group similar RGB colors into 16 levels per channel.
+  const weights = new Float64Array(4096)
+  const reds = new Float64Array(4096)
+  const greens = new Float64Array(4096)
+  const blues = new Float64Array(4096)
+  let visibleWeight = 0
+  let colorfulWeight = 0
+  let largestBucket = 0
+
+  for (let offset = 0; offset < pixels.length; offset += 4) {
+    const r = pixels[offset]
+    const g = pixels[offset + 1]
+    const b = pixels[offset + 2]
+    const weight = pixels[offset + 3] / 255
+    visibleWeight += weight
+
+    const max = Math.max(r, g, b)
+    const min = Math.min(r, g, b)
+    if (
+      weight === 0 ||
+      max < 64 ||
+      min > 230 ||
+      max - min < 40 ||
+      (max - min) / max < 0.15
+    ) {
+      continue
+    }
+
+    const bucket = ((r >> 4) << 8) | ((g >> 4) << 4) | (b >> 4)
+    weights[bucket] += weight
+    reds[bucket] += r * weight
+    greens[bucket] += g * weight
+    blues[bucket] += b * weight
+    colorfulWeight += weight
+    if (weights[bucket] > weights[largestBucket]) largestBucket = bucket
+  }
+
+  // Tiny colorful accents should not determine an otherwise neutral image.
+  if (colorfulWeight === 0 || colorfulWeight < visibleWeight * 0.05) {
+    return undefined
+  }
+  return [reds[largestBucket], greens[largestBucket], blues[largestBucket]].map(
+    (sum) => sum / weights[largestBucket],
+  )
+}
+
+export async function getImageTint(
+  image: Buffer | ImageMetadata,
+  cacheDir?: URL,
+): Promise<string> {
+  if (!Buffer.isBuffer(image)) {
+    // Read the original asset; optimized image URLs may not exist during prerendering.
+    const imagePath: unknown = Reflect.get(image, "fsPath")
+    if (typeof imagePath !== "string") {
+      throw new Error(`Cannot resolve image "${image.src}"`)
+    }
+    image = await readFile(imagePath)
+  }
+
+  const key = createHash("sha256")
+    .update(
+      JSON.stringify({ version: TINT_VERSION, dependencies: sharp.versions }),
+    )
+    .update(image)
+    .digest("hex")
+  const directory = cacheDir && new URL("lightnet/image-tints/", cacheDir)
+  const tintPath = directory && new URL(`${key}.txt`, directory)
+  const memoryKey = `${cacheDir?.href ?? ""}:${key}`
+  const cached = tints.get(memoryKey)
+  if (cached) return cached
+
+  const tint = (async () => {
+    if (tintPath) {
+      try {
+        const value = await readFile(tintPath, "utf8")
+        const channels = /^rgb\((\d+),(\d+),(\d+)\)$/.exec(value)
+        if (
+          channels &&
+          channels.slice(1).every((channel) => Number(channel) <= 255)
+        ) {
+          return value
+        }
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+          console.warn("[lightnet] Cannot read image tint cache:", error)
+        }
+      }
+    }
+    const decoded = await sharp(image)
+      .autoOrient()
+      .resize(432, 502, { fit: "inside" })
+      .toColourspace("srgb")
+      .ensureAlpha()
+      .raw()
+      .toBuffer({ resolveWithObject: true })
+    let color = getChromaticColor(decoded.data)
+    if (!color) {
+      // Materialize flattening before stats(), which reads input pixels directly.
+      const opaque = await sharp(decoded.data, { raw: decoded.info })
+        .flatten({ background: "#fafafa" })
+        .raw()
+        .toBuffer({ resolveWithObject: true })
+      const { dominant } = await sharp(opaque.data, {
+        raw: opaque.info,
+      }).stats()
+      color = [dominant.r, dominant.g, dominant.b]
+    }
+    // Keep every channel at least 170 for readable dark text on any image tint.
+    const value = `rgb(${color
+      .map((channel) => Math.round(250 * 0.68 + channel * 0.32))
+      .join(",")})`
+    if (directory && tintPath) {
+      const temporaryPath = new URL(`${key}.${randomUUID()}.tmp`, directory)
+      try {
+        await mkdir(directory, { recursive: true })
+        await writeFile(temporaryPath, value, { flag: "wx" })
+        await rename(temporaryPath, tintPath)
+      } catch (error) {
+        console.warn("[lightnet] Cannot write image tint cache:", error)
+      } finally {
+        await rm(temporaryPath, { force: true }).catch(() => undefined)
+      }
+    }
+    return value
+  })()
+  if (tints.size >= 128) tints.delete(tints.keys().next().value!)
+  tints.set(memoryKey, tint)
+  void tint.catch(() => {
+    if (tints.get(memoryKey) === tint) tints.delete(memoryKey)
+  })
+  return tint
+}