@rimelight/seo 0.0.5 → 0.0.7

package/dist/types.d.mts

@@ -115,16 +115,17 @@ export interface SiteConfig {
   name: string;
   description: string;
   url: string;
-  ogImage: string;
+  ogImage?: string;
   author: string;
   email: string;
   branding: {
     logo: {
       alt: string;
     };
-    favicon: {
+    favicon?: {
       svg: string;
     };
+    icon?: string;
     colors: {
       themeColor: string;
       backgroundColor: string;
@@ -132,7 +133,7 @@ export interface SiteConfig {
   };
   seo: {
     titleTemplate: string;
-    ogImageFallback: string;
+    ogImageFallback?: string;
     maxDescriptionLength: number;
     authorHandle?: string;
   };
@@ -273,5 +274,264 @@ export interface HeadProps {
    */
   twitter?: TwitterMeta;
 }
+export interface RssItem {
+  title: string;
+  link: string;
+  pubDate: Date | string | number;
+  description?: string;
+  content?: string;
+  guid?: string;
+  author?: string;
+}
+export interface RssFeedOptions {
+  title: string;
+  description: string;
+  site: string;
+  feedUrl?: string;
+  language?: string;
+  items: RssItem[];
+}
+export interface RssCollectionConfig {
+  name: string;
+  pathPrefix?: string;
+}
+export interface RssOptions extends Omit<Partial<RssFeedOptions>, "items"> {
+  /**
+   * Custom RSS route pattern (default: "/rss.xml")
+   */
+  path?: string;
+  /**
+   * Custom items loader or static items array
+   */
+  items?: RssItem[] | (() => Promise<RssItem[]> | RssItem[]);
+  /**
+   * Collections to include in RSS feed (defaults to ["blog", "posts", "news", "articles"])
+   */
+  collections?: (string | RssCollectionConfig)[];
+}
+export interface SitemapOptions {
+  /**
+   * Sitemap route pattern (default: "/sitemap.xml")
+   */
+  path?: string;
+  urls?: SitemapUrl[];
+  entries?: () => Promise<SeoEntry[]> | SeoEntry[];
+  locales?: LocaleConfig;
+  [key: string]: unknown;
+}
+export interface SecurityTxtOptions {
+  /**
+   * Contact URI or list of contact URIs (e.g. "mailto:security@example.com") - REQUIRED by RFC 9116
+   */
+  contact: string | string[];
+  /**
+   * Expiration date/time (ISO 8601 string or Date) - REQUIRED by RFC 9116
+   */
+  expires?: Date | string;
+  /**
+   * URI to PGP/GPG public key
+   */
+  encryption?: string | string[];
+  /**
+   * URI to security acknowledgments / hall of fame
+   */
+  acknowledgments?: string | string[];
+  /**
+   * Comma-separated list of preferred languages (e.g. "en, pt")
+   */
+  preferredLanguages?: string;
+  /**
+   * Canonical URI of the security.txt file
+   */
+  canonical?: string;
+  /**
+   * URI to security policy
+   */
+  policy?: string;
+  /**
+   * URI to security hiring page
+   */
+  hiring?: string;
+  /**
+   * URI to Common Security Advisory Framework (CSAF) provider
+   */
+  csaf?: string;
+}
+export interface SecurityRouteOptions extends Partial<SecurityTxtOptions> {
+  /**
+   * Route pattern (default: "/.well-known/security.txt")
+   */
+  path?: string;
+  /**
+   * Whether to also inject legacy fallback route at "/security.txt" (default: true)
+   */
+  legacyRoute?: boolean;
+}
+export interface WebManifestIcon {
+  src: string;
+  sizes: string;
+  type: string;
+  purpose?: "any" | "maskable" | "monochrome";
+}
+export interface WebManifestShortcut {
+  name: string;
+  url: string;
+  short_name?: string;
+  description?: string;
+  icons?: WebManifestIcon[];
+}
+export interface WebManifest {
+  name: string;
+  short_name?: string;
+  description?: string;
+  start_url: string;
+  display: "fullscreen" | "standalone" | "minimal-ui" | "browser";
+  background_color: string;
+  theme_color: string;
+  icons: WebManifestIcon[];
+  shortcuts?: WebManifestShortcut[];
+  categories?: string[];
+  lang?: string;
+  dir?: "auto" | "ltr" | "rtl";
+  orientation?: "any" | "natural" | "landscape" | "portrait";
+  scope?: string;
+  [key: string]: unknown;
+}
+export interface WebManifestOptions {
+  name: string;
+  shortName?: string;
+  description?: string;
+  startUrl?: string;
+  display?: "fullscreen" | "standalone" | "minimal-ui" | "browser";
+  backgroundColor?: string;
+  themeColor?: string;
+  icons?: WebManifestIcon[];
+  shortcuts?: WebManifestShortcut[];
+  categories?: string[];
+  lang?: string;
+  dir?: "auto" | "ltr" | "rtl";
+  orientation?: "any" | "natural" | "landscape" | "portrait";
+  scope?: string;
+}
+export interface ManifestRouteOptions extends Partial<WebManifestOptions> {
+  /**
+   * Route pattern (default: "/site.webmanifest")
+   */
+  path?: string;
+}
+export interface ApiCatalogItem {
+  rel: string;
+  href: string;
+  type?: string;
+  title?: string;
+  [key: string]: unknown;
+}
+export interface ApiCatalog {
+  "api-catalog": ApiCatalogItem[];
+}
+export interface ApiCatalogOptions {
+  items: ApiCatalogItem[];
+}
+export interface ApiCatalogRouteOptions extends Partial<ApiCatalogOptions> {
+  /**
+   * Route pattern (default: "/.well-known/api-catalog")
+   */
+  path?: string;
+}
+export interface RobotsRouteOptions extends Partial<RobotsOptions> {
+  /**
+   * Route pattern (default: "/robots.txt")
+   */
+  path?: string;
+}
+export interface LlmsRouteOptions extends Partial<LlmsTxtOptions> {
+  /**
+   * Route pattern (default: "/llms.txt")
+   */
+  path?: string;
+}
+export interface LlmsFullRouteOptions extends Partial<LlmsFullTxtOptions> {
+  /**
+   * Route pattern (default: "/llms-full.txt")
+   */
+  path?: string;
+}
+export interface AssetRouteOptions {
+  /**
+   * Path to the master SVG/PNG icon file (relative to project root or absolute). If omitted, will
+   * search in src/assets/logos/ or siteConfig.branding.icon.
+   */
+  icon?: string;
+  /**
+   * Background color for maskable icons (defaults to siteConfig.branding.colors.backgroundColor or
+   * #ffffff)
+   */
+  backgroundColor?: string;
+  /**
+   * Whether to inject /favicon.ico (default: true)
+   */
+  faviconIco?: boolean;
+  /**
+   * Whether to inject /apple-touch-icon.png (default: true)
+   */
+  appleTouchIcon?: boolean;
+  /**
+   * Whether to inject /icon-192.png (default: true)
+   */
+  icon192?: boolean;
+  /**
+   * Whether to inject /icon-512.png (default: true)
+   */
+  icon512?: boolean;
+  /**
+   * Whether to inject /icon-maskable-512.png (default: true)
+   */
+  iconMaskable?: boolean;
+  /**
+   * Whether to generate and emit /og.png branded card (default: true)
+   */
+  ogImage?: boolean;
+}
+export interface RimelightSeoOptions {
+  /**
+   * Sitemap configuration or false to disable automatic /sitemap.xml (default: true)
+   */
+  sitemap?: boolean | SitemapOptions;
+  /**
+   * Robots.txt configuration or false to disable automatic /robots.txt (default: true)
+   */
+  robots?: boolean | RobotsRouteOptions;
+  /**
+   * RSS feed configuration or false to disable automatic /rss.xml (default: true)
+   */
+  rss?: boolean | RssOptions;
+  /**
+   * LLMs.txt configuration or false to disable automatic /llms.txt (default: true)
+   */
+  llms?: boolean | LlmsRouteOptions;
+  /**
+   * LLMs-full.txt configuration or false to disable automatic /llms-full.txt (default: true)
+   */
+  llmsFull?: boolean | LlmsFullRouteOptions;
+  /**
+   * Security.txt configuration or false to disable automatic /.well-known/security.txt (default:
+   * true)
+   */
+  security?: boolean | SecurityRouteOptions;
+  /**
+   * RFC 9652 API Catalog configuration or false to disable automatic /.well-known/api-catalog
+   * (default: true)
+   */
+  apiCatalog?: boolean | ApiCatalogRouteOptions;
+  /**
+   * Web App Manifest configuration or false to disable automatic /site.webmanifest (default: true)
+   */
+  manifest?: boolean | ManifestRouteOptions;
+  /**
+   * Automatic generation of compliant public image assets (favicon.ico, apple-touch-icon.png, PWA
+   * icons) from a single master icon (default: true)
+   */
+  assets?: boolean | AssetRouteOptions;
+}
 //#endregion
 export type { ArticleSchemaOptions, BreadcrumbItem, LlmsFullTxtOptions, LlmsPage, LlmsTxtOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimelight/seo",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "private": false,
   "description": "Rimelight Entertainment's SEO Package",
   "homepage": "https://rimelight.com/docs",
@@ -41,6 +41,30 @@
       "types": "./dist/integration.d.mts",
       "import": "./dist/integration.mjs"
     },
+    "./rss": {
+      "types": "./dist/rss.d.mts",
+      "import": "./dist/rss.mjs"
+    },
+    "./security": {
+      "types": "./dist/security.d.mts",
+      "import": "./dist/security.mjs"
+    },
+    "./manifest": {
+      "types": "./dist/manifest.d.mts",
+      "import": "./dist/manifest.mjs"
+    },
+    "./catalog": {
+      "types": "./dist/catalog.d.mts",
+      "import": "./dist/catalog.mjs"
+    },
+    "./og": {
+      "types": "./dist/og.d.mts",
+      "import": "./dist/og.mjs"
+    },
+    "./assets": {
+      "types": "./dist/assets.d.mts",
+      "import": "./dist/assets.mjs"
+    },
     "./components/*": "./src/components/*",
     "./routes/*": "./src/routes/*",
     "./*": "./src/*"
@@ -49,12 +73,23 @@
     "access": "public"
   },
   "devDependencies": {
-    "@rimelight/config": "0.0.6",
+    "@rimelight/config": "0.0.9",
     "astro": "7.3.2",
+    "sharp": "^0.35.4",
     "typescript": "6.0.3"
   },
   "peerDependencies": {
-    "astro": ">=7.0.0"
+    "astro": ">=7.0.0",
+    "sharp": ">=0.33.0",
+    "takumi-js": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    },
+    "takumi-js": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=26.8.2"

package/src/assets.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from "vite-plus/test"
+import { generatePng, generateMaskablePng, generateIco, generateOgCard } from "./assets.js"
+import sharp from "sharp"
+
+const sampleSvg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="100" height="100">
+  <circle cx="50" cy="50" r="40" fill="#ff0000" />
+</svg>`
+
+describe("Asset Generation", () => {
+  it("generates PNG buffer with correct dimensions", async () => {
+    const pngBuffer = await generatePng(Buffer.from(sampleSvg), { width: 192, height: 192 })
+    expect(pngBuffer).toBeInstanceOf(Buffer)
+
+    const meta = await sharp(pngBuffer).metadata()
+    expect(meta.format).toBe("png")
+    expect(meta.width).toBe(192)
+    expect(meta.height).toBe(192)
+  })
+
+  it("generates maskable PNG buffer with padding and background", async () => {
+    const maskableBuffer = await generateMaskablePng(Buffer.from(sampleSvg), {
+      size: 512,
+      background: "#123456"
+    })
+    expect(maskableBuffer).toBeInstanceOf(Buffer)
+
+    const meta = await sharp(maskableBuffer).metadata()
+    expect(meta.format).toBe("png")
+    expect(meta.width).toBe(512)
+    expect(meta.height).toBe(512)
+  })
+
+  it("generates valid .ico buffer containing PNG data", async () => {
+    const icoBuffer = await generateIco(Buffer.from(sampleSvg), 32)
+    expect(icoBuffer).toBeInstanceOf(Buffer)
+    expect(icoBuffer.length).toBeGreaterThan(22)
+
+    // Verify ICO header
+    expect(icoBuffer.readUInt16LE(0)).toBe(0) // Reserved
+    expect(icoBuffer.readUInt16LE(2)).toBe(1) // Type = 1 (ICO)
+    expect(icoBuffer.readUInt16LE(4)).toBe(1) // 1 image
+
+    // Verify directory entry
+    expect(icoBuffer.readUInt8(6)).toBe(32) // Width
+    expect(icoBuffer.readUInt8(7)).toBe(32) // Height
+    expect(icoBuffer.readUInt16LE(10)).toBe(1) // Planes
+    expect(icoBuffer.readUInt16LE(12)).toBe(32) // 32 bpp
+    expect(icoBuffer.readUInt32LE(18)).toBe(22) // Offset = 22
+
+    // Verify PNG payload inside ICO
+    const pngSlice = icoBuffer.subarray(22)
+    const meta = await sharp(pngSlice).metadata()
+    expect(meta.format).toBe("png")
+    expect(meta.width).toBe(32)
+    expect(meta.height).toBe(32)
+  })
+
+  it("generates standard 1200x630 OG card buffer", async () => {
+    const ogBuffer = await generateOgCard({
+      logoBuffer: Buffer.from(sampleSvg),
+      background: "#0a0a0a"
+    })
+    expect(ogBuffer).toBeInstanceOf(Buffer)
+
+    const meta = await sharp(ogBuffer).metadata()
+    expect(meta.format).toBe("png")
+    expect(meta.width).toBe(1200)
+    expect(meta.height).toBe(630)
+  })
+})

package/src/assets.ts

@@ -0,0 +1,137 @@
+import sharp from "sharp"
+
+export interface GeneratePngOptions {
+  width: number
+  height: number
+  background?: string
+}
+
+export interface GenerateMaskableOptions {
+  size?: number
+  background?: string
+  paddingRatio?: number
+}
+
+export interface GenerateOgCardOptions {
+  width?: number
+  height?: number
+  background?: string
+  logoBuffer?: Buffer | Uint8Array | string | null
+}
+
+/**
+ * Generate a PNG buffer resized to specific dimensions from an SVG or image buffer.
+ */
+export async function generatePng(
+  source: Buffer | Uint8Array | string,
+  options: { width: number; height: number }
+): Promise<Buffer> {
+  return sharp(source)
+    .resize(options.width, options.height, {
+      fit: "contain",
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    })
+    .png()
+    .toBuffer()
+}
+
+/**
+ * Generate a maskable PWA PNG icon with safe-zone padding and solid background. The standard
+ * recommendation is to place the master icon in the inner 80% safe zone.
+ */
+export async function generateMaskablePng(
+  source: Buffer | Uint8Array | string,
+  options: GenerateMaskableOptions = {}
+): Promise<Buffer> {
+  const { size = 512, background = "#ffffff", paddingRatio = 0.15 } = options
+  const innerSize = Math.round(size * (1 - paddingRatio * 2))
+  const pad = Math.floor((size - innerSize) / 2)
+
+  const innerPng = await sharp(source)
+    .resize(innerSize, innerSize, {
+      fit: "contain",
+      background: { r: 0, g: 0, b: 0, alpha: 0 }
+    })
+    .png()
+    .toBuffer()
+
+  return sharp(innerPng)
+    .extend({
+      top: pad,
+      bottom: size - innerSize - pad,
+      left: pad,
+      right: size - innerSize - pad,
+      background
+    })
+    .png()
+    .toBuffer()
+}
+
+/**
+ * Generate a valid .ico buffer containing a 32x32 PNG image according to the Windows ICO
+ * specification.
+ */
+export async function generateIco(
+  source: Buffer | Uint8Array | string,
+  size = 32
+): Promise<Buffer> {
+  const pngBuffer = await generatePng(source, { width: size, height: size })
+
+  const header = Buffer.alloc(22)
+  // Reserved (2 bytes)
+  header.writeUInt16LE(0, 0)
+  // Image type (1 = ICO) (2 bytes)
+  header.writeUInt16LE(1, 2)
+  // Number of images (2 bytes)
+  header.writeUInt16LE(1, 4)
+
+  // Directory entry (16 bytes)
+  header.writeUInt8(size === 256 ? 0 : size, 6) // Width
+  header.writeUInt8(size === 256 ? 0 : size, 7) // Height
+  header.writeUInt8(0, 8) // Palette size (0 = no palette)
+  header.writeUInt8(0, 9) // Reserved
+  header.writeUInt16LE(1, 10) // Color planes
+  header.writeUInt16LE(32, 12) // Bits per pixel (32bpp)
+  header.writeUInt32LE(pngBuffer.length, 14) // Image size in bytes
+  header.writeUInt32LE(22, 18) // Offset of image data (header size = 22)
+
+  return Buffer.concat([header, pngBuffer])
+}
+
+/**
+ * Generate a standard 1200x630 branded Open Graph card from a master logo and background color.
+ */
+export async function generateOgCard(options: GenerateOgCardOptions = {}): Promise<Buffer> {
+  const { width = 1200, height = 630, background = "#0a0a0a", logoBuffer } = options
+
+  if (logoBuffer) {
+    const logoSize = Math.min(Math.round(height * 0.45), 280)
+    const logoPng = await generatePng(logoBuffer, { width: logoSize, height: logoSize })
+    const topPad = Math.floor((height - logoSize) / 2)
+    const bottomPad = height - logoSize - topPad
+    const leftPad = Math.floor((width - logoSize) / 2)
+    const rightPad = width - logoSize - leftPad
+
+    return sharp(logoPng)
+      .extend({
+        top: topPad,
+        bottom: bottomPad,
+        left: leftPad,
+        right: rightPad,
+        background
+      })
+      .png()
+      .toBuffer()
+  }
+
+  return sharp({
+    create: {
+      width,
+      height,
+      channels: 4,
+      background
+    }
+  })
+    .png()
+    .toBuffer()
+}

package/src/catalog.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from "vite-plus/test"
+import { buildApiCatalog } from "./catalog.js"
+
+describe("buildApiCatalog", () => {
+  it("builds linkset api-catalog object", () => {
+    const catalog = buildApiCatalog({
+      items: [
+        {
+          rel: "self",
+          href: "/.well-known/api-catalog",
+          type: "application/linkset+json"
+        },
+        {
+          rel: "alternate",
+          href: "/sitemap.xml",
+          type: "application/xml"
+        }
+      ]
+    })
+
+    const items = catalog["api-catalog"]
+    expect(items).toHaveLength(2)
+    expect(items[0]?.rel).toBe("self")
+    expect(items[1]?.href).toBe("/sitemap.xml")
+  })
+})

package/src/catalog.ts

@@ -0,0 +1,11 @@
+import type { ApiCatalog, ApiCatalogOptions } from "./types.js"
+
+/**
+ * Build RFC 9652 Application Linkset API Catalog. https://www.rfc-editor.org/rfc/rfc9652
+ */
+export function buildApiCatalog(options: ApiCatalogOptions): ApiCatalog {
+  const { items } = options
+  return {
+    "api-catalog": items
+  }
+}

package/src/components/SEOHead.astro

@@ -39,7 +39,7 @@ const {
 // Resolve defaults from config if available
 const siteName = config?.name || 'Rimelight'
 const siteDescription = config?.description || ''
-const ogImageFallback = config?.seo?.ogImageFallback || config?.ogImage || ''
+const ogImageFallback = config?.seo?.ogImageFallback || config?.ogImage || '/og.png'
 const themeColor = config?.branding?.colors?.themeColor
 const favicon = customFavicon || config?.branding?.favicon?.svg || '/favicon.svg'
 const faviconType = favicon.endsWith('.ico')

package/src/env.d.ts

@@ -1,8 +1,56 @@
-declare module "*.astro" {
-  export default {} as import("astro/runtime/server").AstroComponentFactory
-}
 
 declare module "virtual:rimelight-seo-config" {
   const config: import("./integration.js").RimelightSeoOptions
   export default config
 }
+
+declare module "virtual:rimelight-seo/options" {
+  const config: import("./integration.js").RimelightSeoOptions
+  export default config
+}
+
+declare module "virtual:rimelight-seo/config" {
+  export const SEO_LOCALES: import("./types.js").LocaleConfig | undefined
+  export const PRIVATE_PATH_PREFIXES: string[] | undefined
+  export const seoEntries: (() => Promise<import("./types.js").SeoEntry[]>) | undefined
+  export const rssEntries: (() => Promise<import("./types.js").RssItem[]>) | undefined
+}
+
+declare module "virtual:rimelight-seo/site-config" {
+  export const siteConfig: import("./types.js").SiteConfig | Record<string, any>
+}
+
+declare module "virtual:rimelight-seo/db" {
+  export const db: any
+  export const pages: any
+}
+
+declare module "virtual:rimelight-seo/corpus" {
+  export const corpusPages: any[]
+}
+
+declare module "#db/schema" {
+  export const pages: any
+}
+
+declare module "drizzle-orm" {
+  export const and: (...args: any[]) => any
+  export const isNull: (column: any) => any
+  export const isNotNull: (column: any) => any
+  export const sql: any
+  export const eq: (column: any, value: any) => any
+}
+
+declare module "@rimelight/cms" {
+  export const renderCorpusMarkdown: (db: any, options: any) => Promise<string>
+}
+
+declare module "astro:content" {
+  export const getCollection: (collection: string) => Promise<any[]>
+}
+
+declare module "virtual:rimelight-seo/assets" {
+  export const masterIconBuffer: Buffer | null
+  export const isSvg: boolean
+  export const backgroundColor: string
+}