lightnet 4.10.0 → 4.11.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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

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.10.0",
+  "version": "4.11.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/LightNetDev/lightnet",

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,11 +71,13 @@ 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,
-        })
+        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",

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,6 +2,7 @@
 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"
@@ -15,8 +16,10 @@ const { mediaId } = Astro.props
 ---
 
 <DetailsPage mediaId={mediaId} fallbackSchemaType="AudioObject">
-  <MainDetailsSection imageSize="md" mediaId={mediaId} />
-  <AudioPanel mediaId={mediaId} className="mt-10" />
+  <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,6 +1,7 @@
 ---
 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"
@@ -14,9 +15,11 @@ const { mediaId } = Astro.props
 ---
 
 <DetailsPage mediaId={mediaId}>
-  <MainDetailsSection mediaId={mediaId}>
-    <OpenButton className="mt-8" mediaId={mediaId} />
-  </MainDetailsSection>
+  <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,6 +1,7 @@
 ---
 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"
@@ -14,7 +15,9 @@ const { mediaId } = Astro.props
 ---
 
 <DetailsPage mediaId={mediaId} fallbackSchemaType="VideoObject">
-  <VideoDetailsSection mediaId={mediaId} />
+  <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

@@ -1,40 +1,34 @@
-import { readFile } from "node:fs/promises"
-
 import type { APIRoute, GetStaticPaths } from "astro"
-import { getCollection, getEntry } from "astro:content"
+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 { createOpenGraphImage } from "../utils/create-open-graph-image"
+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 config.locales.flatMap((locale) =>
-    items.map(({ id: mediaId }) => ({ params: { locale, mediaId } })),
-  )
+  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)
-  // 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,
-  })
+  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,4 +1,5 @@
 ---
+import { getImage } from "astro:assets"
 import config from "virtual:lightnet/config"
 
 import { getMediaItem } from "../../../content/get-media-items"
@@ -19,7 +20,15 @@ const { defaultLocale, currentLocale, tContentField, tConfigField } =
 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 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,
@@ -45,8 +54,14 @@ const jsonLd = await getDetailsPageJsonLd({
     <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: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} />

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-open-graph-image.ts

@@ -1,6 +1,7 @@
 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
@@ -25,61 +26,74 @@ async function renderText(
   {
     width,
     height,
-    size,
+    maxSize,
     color,
     bold = false,
     rtl = false,
   }: {
     width: number
     height: number
-    size: number
+    maxSize: 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({
+  // 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 " : ""}${fontSize}`,
+        font: `sans ${bold ? "bold " : ""}${size}`,
         width,
+        ...(fit ? { height } : {}),
         wrap: "word-char",
         align: rtl ? "right" : "left",
         rgba: true,
       },
     })
-      .png()
+      .raw()
       .toBuffer({ resolveWithObject: true })
-    if (result.info.height <= height) return result
-    fontSize *= 0.9
-  }
+  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"]
-}) {
+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" })
-    .png()
+    .ensureAlpha()
+    .raw()
     .toBuffer({ resolveWithObject: true })
-  const { dominant } = await sharp(coverImage.data).stats()
+  const tint = await getImageTint(cover, cacheDir)
   const { width: coverWidth, height: coverHeight } = coverImage.info
   const cornerRadius = coverImageStyle === "book" ? 2 : 6
   const decorations: OverlayOptions[] = []
@@ -102,20 +116,17 @@ export async function createOpenGraphImage({
     </svg>`),
     blend: "dest-in",
   })
-  const decoratedCover = await sharp(coverImage.data)
-    .ensureAlpha()
+  const decoratedCover = await sharp(coverImage.data, { raw: coverImage.info })
     .composite(decorations)
-    .png()
-    .toBuffer()
-  const tint = `rgb(${[dominant.r, dominant.g, dominant.b]
-    .map((channel) => Math.round(250 * 0.68 + channel * 0.32))
-    .join(",")})`
+    .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,
+      input: decoratedCover.data,
+      raw: decoratedCover.info,
       left: coverLeft,
       top: coverTop,
     },
@@ -125,7 +136,7 @@ export async function createOpenGraphImage({
     value: string,
     top: number,
     height: number,
-    size: number,
+    maxSize: number,
     color: string,
     bold = false,
   ) => {
@@ -133,13 +144,14 @@ export async function createOpenGraphImage({
     const text = await renderText(value, {
       width: 576,
       height,
-      size,
+      maxSize,
       color,
       bold,
       rtl,
     })
     textLayers.push({
       input: text.data,
+      raw: text.info,
       left: textStart + (rtl ? 576 - text.info.width : 0),
       top,
     })

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-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
+}