@rimelight/seo 0.0.4 → 0.0.5

package/dist/schema.mjs

@@ -0,0 +1,52 @@
+//#region src/schema.ts
+/**
+* Builds Schema.org Article / TechArticle / BlogPosting JSON-LD.
+*/
+function buildArticleSchema(options) {
+	const { type = "TechArticle", title, description, url, datePublished, dateModified, authorName, authorUrl, image, publisherName = "Rimelight Entertainment", publisherLogo } = options;
+	const schema = {
+		"@context": "https://schema.org",
+		"@type": type,
+		"headline": title,
+		"mainEntityOfPage": {
+			"@type": "WebPage",
+			"@id": url
+		}
+	};
+	if (description) schema["description"] = description;
+	if (image) schema["image"] = image;
+	if (datePublished) schema["datePublished"] = datePublished instanceof Date ? datePublished.toISOString() : datePublished;
+	if (dateModified) schema["dateModified"] = dateModified instanceof Date ? dateModified.toISOString() : dateModified;
+	else if (datePublished) schema["dateModified"] = schema["datePublished"];
+	if (authorName) schema["author"] = {
+		"@type": "Person",
+		"name": authorName,
+		...authorUrl ? { url: authorUrl } : {}
+	};
+	if (publisherName) schema["publisher"] = {
+		"@type": "Organization",
+		"name": publisherName,
+		...publisherLogo ? { logo: {
+			"@type": "ImageObject",
+			"url": publisherLogo
+		} } : {}
+	};
+	return schema;
+}
+/**
+* Builds Schema.org BreadcrumbList JSON-LD.
+*/
+function buildBreadcrumbSchema(items) {
+	return {
+		"@context": "https://schema.org",
+		"@type": "BreadcrumbList",
+		"itemListElement": items.map((item, index) => ({
+			"@type": "ListItem",
+			"position": index + 1,
+			"name": item.name,
+			"item": item.url
+		}))
+	};
+}
+//#endregion
+export { buildArticleSchema, buildBreadcrumbSchema };

package/dist/sitemap.d.mts

@@ -1,20 +1,19 @@
-import { r as LocaleConfig, s as SeoEntry, u as SitemapUrl } from "./types-e7gqYZwc.mjs";
+import { LocaleConfig, SeoEntry, SitemapUrl } from "./types.mjs";
 //#region src/sitemap.d.ts
 /**
  * Build fully-resolved sitemap URLs from entries and locale config
  */
-declare function buildSitemapUrls(entries: SeoEntry[], config: LocaleConfig): SitemapUrl[];
+export declare function buildSitemapUrls(entries: SeoEntry[], config: LocaleConfig): SitemapUrl[];
 /**
  * Build sitemap XML from resolved URLs
  */
-declare function buildSitemapXml(urls: SitemapUrl[]): string;
+export declare function buildSitemapXml(urls: SitemapUrl[]): string;
 /**
  * Build sitemap index XML from sitemap URLs
  */
-declare function buildSitemapIndexXml(sitemapUrls: string[]): string;
+export declare function buildSitemapIndexXml(sitemapUrls: string[]): string;
 /**
  * Chunk sitemap URLs into multiple sitemaps (max 50k URLs per sitemap)
  */
-declare function chunkSitemapUrls(urls: SitemapUrl[], limit?: number): SitemapUrl[][];
-//#endregion
-export { buildSitemapIndexXml, buildSitemapUrls, buildSitemapXml, chunkSitemapUrls };
+export declare function chunkSitemapUrls(urls: SitemapUrl[], limit?: number): SitemapUrl[][];
+//#endregion

package/dist/types.d.mts

@@ -1,2 +1,277 @@
-import { _ as ArticleSchemaOptions, a as RSSFeed, c as SiteConfig, d as UserAgentRule, f as LlmsFullTxtOptions, i as OGImage, l as SitemapAlternate, m as LlmsTxtOptions, n as HeadProps, o as RobotsOptions, p as LlmsPage, r as LocaleConfig, s as SeoEntry, t as ChangeFreq, u as SitemapUrl, v as BreadcrumbItem } from "./types-e7gqYZwc.mjs";
-export { type ArticleSchemaOptions, type BreadcrumbItem, ChangeFreq, HeadProps, type LlmsFullTxtOptions, type LlmsPage, type LlmsTxtOptions, LocaleConfig, OGImage, RSSFeed, RobotsOptions, SeoEntry, SiteConfig, SitemapAlternate, SitemapUrl, UserAgentRule };
+import { n as BreadcrumbItem, t as ArticleSchemaOptions } from "./schema-C8v69blQ.mjs";
+import { n as LlmsPage, r as LlmsTxtOptions, t as LlmsFullTxtOptions } from "./llms-BVLxzjr-.mjs";
+//#region src/types.d.ts
+/**
+ * Change frequency for sitemap entries
+ */
+export type ChangeFreq = "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+/**
+ * SEO entry — a single page to include in sitemaps
+ */
+export interface SeoEntry {
+  /**
+   * Locale-less path, e.g. "/company/blog/hello". Leading slash required.
+   */
+  path: string;
+  lastmod?: Date;
+  changefreq?: ChangeFreq;
+  priority?: number;
+  /**
+   * Restrict to a subset of locales; defaults to all configured locales.
+   */
+  locales?: readonly string[];
+}
+/**
+ * Locale configuration for SEO builders
+ */
+export interface LocaleConfig {
+  /**
+   * Absolute origin, e.g. "https://rimelight.com"
+   */
+  site: string;
+  /**
+   * Map of locale segment -> hreflang, e.g. { en: "en-US", pt: "pt-BR" }
+   */
+  locales: Record<string, string>;
+  defaultLocale: string;
+  /**
+   * Emit the default locale without a prefix. Default: false.
+   */
+  prefixDefaultLocale?: boolean;
+  trailingSlash?: "always" | "never";
+}
+/**
+ * Fully resolved sitemap URL with alternates
+ */
+export interface SitemapUrl {
+  loc: string;
+  lastmod?: string;
+  changefreq?: ChangeFreq;
+  priority?: number;
+  alternates?: SitemapAlternate[];
+}
+/**
+ * Language alternate for a sitemap URL
+ */
+export interface SitemapAlternate {
+  hreflang: string;
+  href: string;
+}
+/**
+ * Options for robots.txt generation
+ */
+export interface RobotsOptions {
+  /**
+   * The sitemap URL to reference
+   */
+  sitemapUrl: string;
+  /**
+   * Paths to disallow for all user agents
+   */
+  disallow?: string[];
+  /**
+   * Paths to allow for all user agents
+   */
+  allow?: string[];
+  /**
+   * User-agent specific rules
+   */
+  userAgentRules?: UserAgentRule[];
+}
+/**
+ * User-agent specific robots.txt rule
+ */
+export interface UserAgentRule {
+  userAgent: string;
+  disallow?: string[];
+  allow?: string[];
+}
+export interface OpenGraphMeta {
+  type?: string;
+  locale?: string;
+  url?: string;
+  title?: string;
+  description?: string;
+  images?: OGImage[] | OGImage;
+  siteName?: string;
+  [key: string]: unknown;
+}
+export interface TwitterMeta {
+  card?: "summary" | "summary_large_image" | "player" | "app";
+  site?: string;
+  creator?: string;
+  title?: string;
+  description?: string;
+  images?: OGImage[] | OGImage | string;
+  [key: string]: unknown;
+}
+/**
+ * Site identity and SEO defaults shared across all Rimelight Astro sites. The UI-specific overrides
+ * (component themes, shortcuts, etc.) live in UIConfig (packages/ui) and are passed directly to the
+ * ui() integration.
+ */
+export interface SiteConfig {
+  id: string;
+  name: string;
+  description: string;
+  url: string;
+  ogImage: string;
+  author: string;
+  email: string;
+  branding: {
+    logo: {
+      alt: string;
+    };
+    favicon: {
+      svg: string;
+    };
+    colors: {
+      themeColor: string;
+      backgroundColor: string;
+    };
+  };
+  seo: {
+    titleTemplate: string;
+    ogImageFallback: string;
+    maxDescriptionLength: number;
+    authorHandle?: string;
+  };
+  openGraph?: OpenGraphMeta;
+  twitter?: TwitterMeta;
+}
+/**
+ * Open Graph image with alt text
+ */
+export interface OGImage {
+  /**
+   * Image URL (relative or absolute)
+   */
+  src: string;
+  /**
+   * Alt text for the image
+   */
+  alt: string;
+}
+/**
+ * RSS feed link configuration
+ */
+export interface RSSFeed {
+  /**
+   * RSS feed URL
+   */
+  href: string;
+  /**
+   * Feed title (defaults to "RSS")
+   */
+  title?: string;
+}
+/**
+ * Props for the RLAHead Astro component. Defined here so consumers can construct head props without
+ * importing @rimelight/ui.
+ */
+export interface HeadProps {
+  /**
+   * Page title
+   */
+  title?: string;
+  /**
+   * Page description
+   */
+  description?: string;
+  /**
+   * Open Graph image with alt text
+   */
+  ogImage?: OGImage;
+  /**
+   * Open Graph type (e.g., "website", "article")
+   */
+  ogType?: string;
+  /**
+   * Open Graph locale (defaults to "en_US")
+   */
+  ogLocale?: string;
+  /**
+   * Whether to prevent indexing
+   */
+  noindex?: boolean;
+  /**
+   * Whether this is a 404 page
+   */
+  is404?: boolean;
+  /**
+   * Robots metadata (overrides noindex/is404 logic if provided)
+   */
+  robots?: string;
+  /**
+   * Canonical URL
+   */
+  canonical?: string;
+  /**
+   * Language alternates for i18n
+   */
+  languageAlternates?: Array<{
+    hreflang: string;
+    href: string;
+  }>;
+  /**
+   * Custom favicon SVG or image path (overrides config.branding.favicon.svg)
+   */
+  favicon?: string;
+  /**
+   * Site configuration for defaults
+   */
+  config?: SiteConfig;
+  /**
+   * Whether to enable View Transitions (ClientRouter)
+   */
+  transitions?: boolean;
+  /**
+   * Meta charset
+   */
+  charset?: string;
+  /**
+   * Meta viewport
+   */
+  viewport?: string;
+  /**
+   * RSS feed configuration
+   */
+  rssFeed?: RSSFeed;
+  /**
+   * Article or BlogPosting JSON-LD configuration
+   */
+  articleSchema?: ArticleSchemaOptions;
+  /**
+   * Breadcrumb list for JSON-LD structured data
+   */
+  breadcrumbs?: BreadcrumbItem[];
+  /**
+   * URL for this page's raw Markdown alternate twin
+   */
+  markdownUrl?: string;
+  /**
+   * Version alternates for multi-version documentation
+   */
+  versionAlternates?: Array<{
+    version: string;
+    href: string;
+  }>;
+  /**
+   * Whether the title should bypass site title template
+   */
+  absolute?: boolean;
+  /**
+   * Twitter card type
+   */
+  twitterCard?: "summary" | "summary_large_image" | "player" | "app";
+  /**
+   * Open Graph metadata overrides
+   */
+  openGraph?: OpenGraphMeta;
+  /**
+   * Twitter metadata overrides
+   */
+  twitter?: TwitterMeta;
+}
+//#endregion
+export type { ArticleSchemaOptions, BreadcrumbItem, LlmsFullTxtOptions, LlmsPage, LlmsTxtOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimelight/seo",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "private": false,
   "description": "Rimelight Entertainment's SEO Package",
   "homepage": "https://rimelight.com/docs",
@@ -37,22 +37,27 @@
       "types": "./dist/robots.d.mts",
       "import": "./dist/robots.mjs"
     },
+    "./integration": {
+      "types": "./dist/integration.d.mts",
+      "import": "./dist/integration.mjs"
+    },
     "./components/*": "./src/components/*",
+    "./routes/*": "./src/routes/*",
     "./*": "./src/*"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@rimelight/config": "0.0.5",
-    "astro": "7.3.1",
+    "@rimelight/config": "0.0.6",
+    "astro": "7.3.2",
     "typescript": "6.0.3"
   },
   "peerDependencies": {
     "astro": ">=7.0.0"
   },
   "engines": {
-    "node": ">=26.7.0"
+    "node": ">=26.8.2"
   },
   "scripts": {
     "build": "vp pack",

package/src/components/SEOHead.astro

@@ -1,11 +1,12 @@
 ---
-import type { HeadProps } from "../types.js"
+import type { HeadProps, OpenGraphMeta, TwitterMeta } from "../types.js"
 import {
   buildCanonicalUrl,
   buildPageTitle,
   buildSafeDescription,
   buildRobotsMetaContent,
-  buildWebSiteSchema
+  buildWebSiteSchema,
+  deepMerge
 } from "../meta.js"
 import { buildArticleSchema, buildBreadcrumbSchema } from "../schema.js"
 
@@ -29,6 +30,10 @@ const {
   breadcrumbs,
   markdownUrl,
   versionAlternates = [],
+  absolute = false,
+  twitterCard,
+  openGraph,
+  twitter,
 } = Astro.props as HeadProps
 
 // Resolve defaults from config if available
@@ -50,7 +55,8 @@ const displayTitle = buildPageTitle({
   ...(title !== undefined && { title }),
   siteName,
   titleTemplate,
-  ...(is404 !== undefined && { is404 })
+  ...(is404 !== undefined && { is404 }),
+  ...(absolute !== undefined && { absolute })
 })
 
 const finalDescription = description || siteDescription
@@ -72,6 +78,47 @@ const robotsContent = buildRobotsMetaContent({
   is404,
   ...(robots !== undefined && { override: robots })
 })
+
+// Deep-merged OpenGraph
+const defaultOpenGraph: OpenGraphMeta = {
+  type: ogType,
+  locale: ogLocale,
+  url: Astro.url.href,
+  title: title || siteName,
+  ...(safeDescription && { description: safeDescription }),
+  ...(absoluteOgImage && { images: [{ src: absoluteOgImage, alt: finalOgImage?.alt || siteName }] }),
+  siteName,
+  ...config?.openGraph,
+}
+const resolvedOpenGraph = deepMerge(defaultOpenGraph, openGraph || {})
+if (ogImage) {
+  resolvedOpenGraph.images = ogImage
+}
+const ogImgUrl = resolvedOpenGraph.images
+  ? (Array.isArray(resolvedOpenGraph.images) ? resolvedOpenGraph.images[0]?.src : (typeof resolvedOpenGraph.images === 'string' ? resolvedOpenGraph.images : resolvedOpenGraph.images.src))
+  : absoluteOgImage
+const ogImgAlt = resolvedOpenGraph.images
+  ? (Array.isArray(resolvedOpenGraph.images) ? resolvedOpenGraph.images[0]?.alt : (typeof resolvedOpenGraph.images === 'object' && 'alt' in resolvedOpenGraph.images ? resolvedOpenGraph.images.alt : finalOgImage?.alt || siteName))
+  : finalOgImage?.alt || siteName
+
+const absoluteResolvedOgImage = ogImgUrl ? new URL(ogImgUrl, Astro.site ?? Astro.url).toString() : undefined
+
+// Deep-merged Twitter
+const defaultTwitter: TwitterMeta = {
+  card: twitterCard || config?.twitter?.card || (absoluteResolvedOgImage ? 'summary_large_image' : 'summary'),
+  ...(twitterHandle && { site: twitterHandle, creator: twitterHandle }),
+  title: resolvedOpenGraph.title || title || siteName,
+  ...(safeDescription && { description: safeDescription }),
+  ...(absoluteResolvedOgImage && { images: absoluteResolvedOgImage }),
+  ...config?.twitter,
+}
+const resolvedTwitter = deepMerge(defaultTwitter, twitter || {})
+if (twitterCard) {
+  resolvedTwitter.card = twitterCard
+}
+if (!resolvedTwitter.card) {
+  resolvedTwitter.card = absoluteResolvedOgImage ? 'summary_large_image' : 'summary'
+}
 ---
 
 <!-- Basic Metadata -->
@@ -103,24 +150,24 @@ const robotsContent = buildRobotsMetaContent({
 ))}
 
 <!-- Open Graph / Facebook -->
-<meta property="og:type" content={ogType} />
-<meta property="og:locale" content={ogLocale} />
-<meta property="og:url" content={Astro.url.href} />
-<meta property="og:title" content={title || siteName} />
-{safeDescription && <meta property="og:description" content={safeDescription} />}
-{absoluteOgImage && <meta property="og:image" content={absoluteOgImage} />}
-{finalOgImage && <meta property="og:image:alt" content={finalOgImage.alt} />}
-<meta property="og:site_name" content={siteName} />
+<meta property="og:type" content={resolvedOpenGraph.type || 'website'} />
+<meta property="og:locale" content={resolvedOpenGraph.locale || 'en_US'} />
+<meta property="og:url" content={resolvedOpenGraph.url || Astro.url.href} />
+<meta property="og:title" content={resolvedOpenGraph.title || title || siteName} />
+{resolvedOpenGraph.description && <meta property="og:description" content={resolvedOpenGraph.description} />}
+{absoluteResolvedOgImage && <meta property="og:image" content={absoluteResolvedOgImage} />}
+{ogImgAlt && <meta property="og:image:alt" content={ogImgAlt} />}
+<meta property="og:site_name" content={resolvedOpenGraph.siteName || siteName} />
 
 <!-- Twitter -->
-<meta property="twitter:card" content="summary_large_image" />
+<meta property="twitter:card" content={resolvedTwitter.card} />
 <meta property="twitter:url" content={Astro.url.href} />
-<meta property="twitter:title" content={title || siteName} />
-{safeDescription && <meta property="twitter:description" content={safeDescription} />}
-{absoluteOgImage && <meta property="twitter:image" content={absoluteOgImage} />}
-{finalOgImage && <meta property="twitter:image:alt" content={finalOgImage.alt} />}
-{twitterHandle && <meta property="twitter:site" content={twitterHandle} />}
-{twitterHandle && <meta property="twitter:creator" content={twitterHandle} />}
+<meta property="twitter:title" content={resolvedTwitter.title || title || siteName} />
+{resolvedTwitter.description && <meta property="twitter:description" content={resolvedTwitter.description} />}
+{absoluteResolvedOgImage && <meta property="twitter:image" content={absoluteResolvedOgImage} />}
+{ogImgAlt && <meta property="twitter:image:alt" content={ogImgAlt} />}
+{resolvedTwitter.site && <meta property="twitter:site" content={resolvedTwitter.site} />}
+{resolvedTwitter.creator && <meta property="twitter:creator" content={resolvedTwitter.creator} />}
 
 <!-- Icons & Manifest -->
 <link rel="icon" type={faviconType} href={favicon} />

package/src/env.d.ts

@@ -1,3 +1,8 @@
 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
+}

package/src/index.ts

@@ -10,6 +10,8 @@ export type {
   OGImage,
   RSSFeed,
   HeadProps,
+  OpenGraphMeta,
+  TwitterMeta,
   LlmsPage,
   LlmsTxtOptions,
   LlmsFullTxtOptions,
@@ -31,8 +33,10 @@ export {
   buildPageTitle,
   buildSafeDescription,
   buildRobotsMetaContent,
-  buildWebSiteSchema
+  buildWebSiteSchema,
+  deepMerge
 } from "./meta.js"
 
 export { buildLlmsTxt, buildLlmsFullTxt } from "./llms.js"
 export { buildArticleSchema, buildBreadcrumbSchema } from "./schema.js"
+export { rimelightSeo, type RimelightSeoOptions } from "./integration.js"

package/src/integration.ts

@@ -0,0 +1,74 @@
+import type { AstroIntegration } from "astro"
+import type { RobotsOptions, SitemapUrl, LlmsTxtOptions } from "./types.js"
+
+export interface RimelightSeoOptions {
+  /**
+   * Sitemap configuration or false to disable automatic /sitemap.xml
+   */
+  sitemap?:
+    | boolean
+    | {
+        urls?: SitemapUrl[]
+        [key: string]: any
+      }
+  /**
+   * Robots.txt configuration or false to disable automatic /robots.txt
+   */
+  robots?: boolean | RobotsOptions
+  /**
+   * LLMs.txt configuration or false to disable automatic /llms.txt
+   */
+  llms?: boolean | LlmsTxtOptions
+}
+
+export function rimelightSeo(options: RimelightSeoOptions = {}): AstroIntegration {
+  return {
+    name: "@rimelight/seo",
+    hooks: {
+      "astro:config:setup": ({ injectRoute, updateConfig }) => {
+        if (options.robots !== false) {
+          injectRoute({
+            pattern: "/robots.txt",
+            entrypoint: "@rimelight/seo/routes/robots.txt.ts"
+          })
+        }
+
+        if (options.sitemap !== false) {
+          injectRoute({
+            pattern: "/sitemap.xml",
+            entrypoint: "@rimelight/seo/routes/sitemap.xml.ts"
+          })
+        }
+
+        if (options.llms !== false) {
+          injectRoute({
+            pattern: "/llms.txt",
+            entrypoint: "@rimelight/seo/routes/llms.txt.ts"
+          })
+        }
+
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "vite-plugin-rimelight-seo",
+                resolveId(id) {
+                  if (id === "virtual:rimelight-seo-config") {
+                    return "\0virtual:rimelight-seo-config"
+                  }
+                  return null
+                },
+                load(id) {
+                  if (id === "\0virtual:rimelight-seo-config") {
+                    return `export default ${JSON.stringify(options)};`
+                  }
+                  return null
+                }
+              }
+            ]
+          }
+        })
+      }
+    }
+  }
+}

package/src/meta.test.ts

@@ -4,7 +4,8 @@ import {
   buildPageTitle,
   buildSafeDescription,
   buildRobotsMetaContent,
-  buildWebSiteSchema
+  buildWebSiteSchema,
+  deepMerge
 } from "./meta.js"
 
 const BASE = "https://example.com"
@@ -49,6 +50,29 @@ describe("buildPageTitle", () => {
       "404 - Not Found | My Site"
     )
   })
+
+  it("bypasses title template when absolute is true", () => {
+    expect(buildPageTitle({ ...opts, title: "Landing Page", absolute: true })).toBe("Landing Page")
+  })
+})
+
+describe("deepMerge", () => {
+  it("deep merges nested objects", () => {
+    const base = {
+      openGraph: { type: "website", siteName: "Base", locale: "en_US" },
+      twitter: { card: "summary", site: "@base" }
+    }
+    const override = {
+      openGraph: { siteName: "Override" },
+      twitter: { card: "summary_large_image" }
+    }
+    const result = deepMerge(base, override)
+    expect(result.openGraph.type).toBe("website")
+    expect(result.openGraph.siteName).toBe("Override")
+    expect(result.openGraph.locale).toBe("en_US")
+    expect(result.twitter.card).toBe("summary_large_image")
+    expect(result.twitter.site).toBe("@base")
+  })
 })
 
 describe("buildSafeDescription", () => {