@rimelight/seo 0.0.1

package/README.md

@@ -0,0 +1,19 @@
+# Rimelight Entertainment Workspace
+
+## Structure
+
+### Apps (`/packages`)
+
+- **`rimelight.com`**: The main company website.
+- **`starter.rimelight.com`**: Our standardized starter template for Astro websites.
+
+### Packages (`/packages`)
+
+- **`@rimelight/auth`**: Authentication and authorization utilities for the Rimelight ecosystem.
+- **`@rimelight/cli`**: The command line interface for managing Rimelight projects.
+- **`@rimelight/cms`**: Enterprise content management, block rendering, and wiki engine.
+- **`@rimelight/docs`**: Documentation components and utilities.
+- **`@rimelight/i18n`**: Internationalization and localization tools.
+- **`@rimelight/security`**: Astro security integration (CSP, SRI, and more).
+- **`@rimelight/seo`**: SEO utilities including sitemap, robots, and meta components.
+- **`@rimelight/ui`**: Our component library used in all our web projects.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@rimelight/seo",
+  "version": "0.0.1",
+  "private": false,
+  "description": "Rimelight Entertainment's SEO Package",
+  "homepage": "https://rimelight.com/docs",
+  "bugs": {
+    "url": "https://github.com/Rimelight-Entertainment/rimelight/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Rimelight Entertainment"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rimelight-Entertainment/rimelight.git"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",
+    "./sitemap": "./src/sitemap.ts",
+    "./robots": "./src/robots.ts",
+    "./components/*": "./src/components/*",
+    "./*": "./src/*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "pnpm audit --audit-level=moderate && vp check --fix && astro check"
+  },
+  "devDependencies": {
+    "@rimelight/config": "workspace:*",
+    "astro": "7.2.2",
+    "typescript": "6.0.3"
+  },
+  "peerDependencies": {
+    "astro": ">=7.0.0"
+  },
+  "engines": {
+    "node": ">=26.7.0"
+  },
+  "packageManager": "pnpm@11.22.0"
+}

package/src/components/SEOHead.astro

@@ -0,0 +1,124 @@
+---
+import type { HeadProps } from "../types.js"
+import {
+  buildCanonicalUrl,
+  buildPageTitle,
+  buildSafeDescription,
+  buildRobotsMetaContent,
+  buildWebSiteSchema
+} from "../meta.js"
+
+const {
+  title,
+  description,
+  ogImage,
+  ogType = 'website',
+  ogLocale = 'en_US',
+  noindex = false,
+  is404 = false,
+  robots,
+  canonical,
+  languageAlternates = [],
+  config,
+  charset = 'utf-8',
+  viewport = 'width=device-width, initial-scale=1',
+  rssFeed,
+} = Astro.props as HeadProps
+
+// Resolve defaults from config if available
+const siteName = config?.name || 'Rimelight'
+const siteDescription = config?.description || ''
+const ogImageFallback = config?.seo?.ogImageFallback || config?.ogImage || ''
+const themeColor = config?.branding?.colors?.themeColor
+const favicon = config?.branding?.favicon?.svg || '/favicon.svg'
+const twitterHandle = config?.seo?.authorHandle
+const titleTemplate = config?.seo?.titleTemplate || `%s | ${siteName}`
+
+// Calculated Values
+const displayTitle = buildPageTitle({
+  ...(title !== undefined && { title }),
+  siteName,
+  titleTemplate,
+  ...(is404 !== undefined && { is404 })
+})
+
+const finalDescription = description || siteDescription
+const safeDescription = config?.seo?.maxDescriptionLength
+  ? buildSafeDescription(finalDescription, config.seo.maxDescriptionLength)
+  : finalDescription
+
+const finalOgImage = ogImage || (ogImageFallback ? { src: ogImageFallback, alt: siteName } : undefined)
+const absoluteOgImage = finalOgImage
+  ? new URL(finalOgImage.src, Astro.site ?? Astro.url).toString()
+  : undefined
+
+const finalCanonical = canonical
+  ? buildCanonicalUrl(canonical, Astro.site ?? Astro.url)
+  : (!is404 ? buildCanonicalUrl(Astro.url, Astro.site ?? Astro.url) : undefined)
+
+const robotsContent = buildRobotsMetaContent({
+  noindex,
+  is404,
+  ...(robots !== undefined && { override: robots })
+})
+---
+
+<!-- Basic Metadata -->
+<meta charset={charset} />
+<meta name="viewport" content={viewport} />
+<meta name="generator" content={Astro.generator} />
+
+<!-- Sitemap -->
+<link rel="sitemap" href="/sitemap.xml" />
+
+<!-- RSS Feed -->
+{rssFeed && <link rel="alternate" type="application/rss+xml" href={rssFeed.href} title={rssFeed.title || 'RSS'} />}
+
+<!-- SEO -->
+<title>{displayTitle}</title>
+{safeDescription && <meta name="description" content={safeDescription} />}
+<meta name="robots" content={robotsContent} />
+{finalCanonical && <link rel="canonical" href={finalCanonical} />}
+
+<!-- i18n Alternates -->
+{languageAlternates.map((alt) => (
+  <link rel="alternate" hreflang={alt.hreflang} href={alt.href} />
+))}
+
+<!-- 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} />
+
+<!-- Twitter -->
+<meta property="twitter:card" content="summary_large_image" />
+<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} />}
+
+<!-- Icons & Manifest -->
+<link rel="icon" type="image/svg+xml" href={favicon} />
+<link rel="icon" href="/favicon.ico" sizes="32x32" />
+<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+<link rel="manifest" href="/site.webmanifest" />
+
+<!-- Theme Metadata -->
+<meta name="color-scheme" content="light dark" />
+<meta name="theme-color" media="(prefers-color-scheme: light)" content={themeColor || "#ffffff"} />
+<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0a0a0a" />
+
+<!-- Structured Data -->
+{config && (
+  <script type="application/ld+json" is:inline set:html={JSON.stringify(
+    buildWebSiteSchema(config, Astro.site?.toString())
+  )} />
+)}

package/src/env.d.ts

@@ -0,0 +1,3 @@
+declare module "*.astro" {
+  export default {} as import("astro/runtime/server").AstroComponentFactory
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+export type {
+  ChangeFreq,
+  LocaleConfig,
+  RobotsOptions,
+  SeoEntry,
+  SitemapAlternate,
+  SitemapUrl,
+  UserAgentRule,
+  SiteConfig,
+  OGImage,
+  RSSFeed,
+  HeadProps
+} from "./types.js"
+
+export {
+  buildSitemapUrls,
+  buildSitemapXml,
+  buildSitemapIndexXml,
+  chunkSitemapUrls
+} from "./sitemap.js"
+
+export { buildRobotsTxt } from "./robots.js"
+
+export {
+  buildCanonicalUrl,
+  buildPageTitle,
+  buildSafeDescription,
+  buildRobotsMetaContent,
+  buildWebSiteSchema
+} from "./meta.js"

package/src/meta.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from "vite-plus/test"
+import {
+  buildCanonicalUrl,
+  buildPageTitle,
+  buildSafeDescription,
+  buildRobotsMetaContent,
+  buildWebSiteSchema
+} from "./meta.js"
+
+const BASE = "https://example.com"
+
+describe("buildCanonicalUrl", () => {
+  it("adds trailing slash to clean paths", () => {
+    expect(buildCanonicalUrl("/about", BASE)).toBe("https://example.com/about/")
+  })
+
+  it("strips trailing slash from query-param paths", () => {
+    expect(buildCanonicalUrl("/search?q=hello", BASE)).toBe("https://example.com/search?q=hello")
+  })
+
+  it("handles root path", () => {
+    expect(buildCanonicalUrl("/", BASE)).toBe("https://example.com/")
+  })
+
+  it("resolves relative paths against base", () => {
+    expect(buildCanonicalUrl(new URL("https://example.com/docs"), BASE)).toBe(
+      "https://example.com/docs/"
+    )
+  })
+})
+
+describe("buildPageTitle", () => {
+  const opts = { siteName: "My Site", titleTemplate: "%s | My Site" }
+
+  it("applies title template", () => {
+    expect(buildPageTitle({ ...opts, title: "About" })).toBe("About | My Site")
+  })
+
+  it("returns siteName when no title", () => {
+    expect(buildPageTitle(opts)).toBe("My Site")
+  })
+
+  it("returns 404 label for error pages", () => {
+    expect(buildPageTitle({ ...opts, is404: true })).toBe("404 - Not Found | My Site")
+  })
+
+  it("404 overrides title if both provided", () => {
+    expect(buildPageTitle({ ...opts, title: "Oops", is404: true })).toBe(
+      "404 - Not Found | My Site"
+    )
+  })
+})
+
+describe("buildSafeDescription", () => {
+  it("returns description unchanged when within limit", () => {
+    expect(buildSafeDescription("Short desc", 160)).toBe("Short desc")
+  })
+
+  it("truncates and appends ellipsis when over limit", () => {
+    const long = "a".repeat(200)
+    const result = buildSafeDescription(long, 160)
+    expect(result).toHaveLength(160)
+    expect(result.endsWith("...")).toBe(true)
+  })
+
+  it("handles empty string", () => {
+    expect(buildSafeDescription("", 160)).toBe("")
+  })
+
+  it("truncates at exact boundary", () => {
+    const text = "a".repeat(160)
+    expect(buildSafeDescription(text, 160)).toBe(text)
+    expect(buildSafeDescription(text + "b", 160)).toHaveLength(160)
+  })
+})
+
+describe("buildRobotsMetaContent", () => {
+  it("returns indexable string by default", () => {
+    expect(buildRobotsMetaContent({})).toBe("index, follow, max-image-preview:large")
+  })
+
+  it("returns noindex for noindex=true", () => {
+    expect(buildRobotsMetaContent({ noindex: true })).toBe("noindex, nofollow")
+  })
+
+  it("returns noindex for is404=true", () => {
+    expect(buildRobotsMetaContent({ is404: true })).toBe("noindex, nofollow")
+  })
+
+  it("respects override", () => {
+    expect(buildRobotsMetaContent({ override: "noarchive" })).toBe("noarchive")
+  })
+})
+
+describe("buildWebSiteSchema", () => {
+  const config = { name: "My Site", url: "https://example.com", description: "A test site" }
+
+  it("builds schema.org WebSite object", () => {
+    const schema = buildWebSiteSchema(config)
+    expect(schema["@context"]).toBe("https://schema.org")
+    expect(schema["@type"]).toBe("WebSite")
+    expect(schema.name).toBe("My Site")
+    expect(schema.url).toBe("https://example.com")
+  })
+
+  it("prefers site param over config.url", () => {
+    const schema = buildWebSiteSchema(config, "https://override.com")
+    expect(schema.url).toBe("https://override.com")
+  })
+})

package/src/meta.ts

@@ -0,0 +1,70 @@
+import type { SiteConfig } from "./types.js"
+
+/**
+ * Build a canonical URL from a page URL and site base. - Strips trailing slash unless the path has
+ * query params (where trailing slash is removed too). - Returns undefined-safe: pass Astro.url and
+ * Astro.site directly.
+ */
+export function buildCanonicalUrl(url: string | URL, base: string | URL): string {
+  const resolved = new URL(url, base)
+  const path = resolved.toString()
+  // Keep query params as-is but strip trailing slash; for clean paths also ensure trailing slash
+  return path.includes("?") ? path.replace(/\/?$/, "") : path.replace(/\/?$/, "/")
+}
+
+/**
+ * Build a page title using a site's title template. Falls back to siteName for untitled pages; uses
+ * a 404 label for error pages.
+ */
+export function buildPageTitle(opts: {
+  title?: string
+  siteName: string
+  titleTemplate: string
+  is404?: boolean
+}): string {
+  const { title, siteName, titleTemplate, is404 } = opts
+  if (is404) return `404 - Not Found | ${siteName}`
+  if (!title) return siteName
+  return titleTemplate.replace("%s", title)
+}
+
+/**
+ * Truncate a description to a maximum character length, appending "…" if trimmed.
+ */
+export function buildSafeDescription(description: string, maxLength: number): string {
+  if (!description) return description
+  if (description.length <= maxLength) return description
+  return description.slice(0, maxLength - 3) + "..."
+}
+
+/**
+ * Build the value for the <meta name="robots"> tag. Returns the full directive string including
+ * max-image-preview for indexable pages.
+ */
+export function buildRobotsMetaContent(opts: {
+  noindex?: boolean
+  is404?: boolean
+  override?: string
+}): string {
+  if (opts.override) return opts.override
+  return !opts.noindex && !opts.is404
+    ? "index, follow, max-image-preview:large"
+    : "noindex, nofollow"
+}
+
+/**
+ * \n * Build a Schema.org WebSite JSON-LD object.\n * Pass the result to JSON.stringify and emit
+ * via <script type="application/ld+json">.\n
+ */
+export function buildWebSiteSchema(
+  config: Pick<SiteConfig, "name" | "url" | "description">,
+  site?: string
+): Record<string, unknown> {
+  return {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    "name": config.name,
+    "url": site ?? config.url,
+    "description": config.description
+  }
+}

package/src/robots.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "vite-plus/test"
+import { buildRobotsTxt } from "./robots.js"
+import type { RobotsOptions } from "./types.js"
+
+describe("buildRobotsTxt", () => {
+  it("generates basic robots.txt with sitemap", () => {
+    const options: RobotsOptions = {
+      sitemapUrl: "https://example.com/sitemap.xml"
+    }
+
+    const robots = buildRobotsTxt(options)
+
+    expect(robots).toContain("User-agent: *")
+    expect(robots).toContain("Sitemap: https://example.com/sitemap.xml")
+  })
+
+  it("includes disallow rules", () => {
+    const options: RobotsOptions = {
+      sitemapUrl: "https://example.com/sitemap.xml",
+      disallow: ["/admin/", "/dashboard/"]
+    }
+
+    const robots = buildRobotsTxt(options)
+
+    expect(robots).toContain("Disallow: /admin/")
+    expect(robots).toContain("Disallow: /dashboard/")
+  })
+
+  it("includes allow rules", () => {
+    const options: RobotsOptions = {
+      sitemapUrl: "https://example.com/sitemap.xml",
+      allow: ["/api/public/"]
+    }
+
+    const robots = buildRobotsTxt(options)
+
+    expect(robots).toContain("Allow: /api/public/")
+  })
+
+  it("includes user-agent specific rules", () => {
+    const options: RobotsOptions = {
+      sitemapUrl: "https://example.com/sitemap.xml",
+      userAgentRules: [
+        {
+          userAgent: "GPTBot",
+          disallow: ["/admin/"]
+        }
+      ]
+    }
+
+    const robots = buildRobotsTxt(options)
+
+    expect(robots).toContain("User-agent: GPTBot")
+    expect(robots).toContain("Disallow: /admin/")
+  })
+
+  it("orders user-agent specific rules before wildcard", () => {
+    const options: RobotsOptions = {
+      sitemapUrl: "https://example.com/sitemap.xml",
+      userAgentRules: [
+        {
+          userAgent: "GPTBot",
+          disallow: ["/admin/"]
+        }
+      ]
+    }
+
+    const robots = buildRobotsTxt(options)
+
+    const gptBotIndex = robots.indexOf("User-agent: GPTBot")
+    const wildcardIndex = robots.indexOf("User-agent: *")
+
+    expect(gptBotIndex).toBeLessThan(wildcardIndex)
+  })
+})

package/src/robots.ts

@@ -0,0 +1,59 @@
+import type { RobotsOptions, UserAgentRule } from "./types.js"
+
+/**
+ * Build robots.txt content from options
+ */
+export function buildRobotsTxt(options: RobotsOptions): string {
+  const lines: string[] = []
+
+  // Add user-agent specific rules first
+  if (options.userAgentRules && options.userAgentRules.length > 0) {
+    for (const rule of options.userAgentRules) {
+      lines.push(buildUserAgentSection(rule))
+      lines.push("")
+    }
+  }
+
+  // Add wildcard user-agent (all bots)
+  lines.push("User-agent: *")
+
+  if (options.disallow && options.disallow.length > 0) {
+    for (const path of options.disallow) {
+      lines.push(`Disallow: ${path}`)
+    }
+  }
+
+  if (options.allow && options.allow.length > 0) {
+    for (const path of options.allow) {
+      lines.push(`Allow: ${path}`)
+    }
+  }
+
+  lines.push("")
+  lines.push(`Sitemap: ${options.sitemapUrl}`)
+
+  return lines.join("\n")
+}
+
+/**
+ * Build a user-agent specific section
+ */
+function buildUserAgentSection(rule: UserAgentRule): string {
+  const lines: string[] = []
+
+  lines.push(`User-agent: ${rule.userAgent}`)
+
+  if (rule.disallow && rule.disallow.length > 0) {
+    for (const path of rule.disallow) {
+      lines.push(`Disallow: ${path}`)
+    }
+  }
+
+  if (rule.allow && rule.allow.length > 0) {
+    for (const path of rule.allow) {
+      lines.push(`Allow: ${path}`)
+    }
+  }
+
+  return lines.join("\n")
+}

package/src/sitemap.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect } from "vite-plus/test"
+import {
+  buildSitemapUrls,
+  buildSitemapXml,
+  buildSitemapIndexXml,
+  chunkSitemapUrls
+} from "./sitemap.js"
+import type { LocaleConfig, SeoEntry } from "./types.js"
+
+describe("buildSitemapUrls", () => {
+  const config: LocaleConfig = {
+    site: "https://example.com",
+    locales: { en: "en-US", pt: "pt-BR" },
+    defaultLocale: "en"
+  }
+
+  it("builds URLs for a single entry in multiple locales", () => {
+    const entries: SeoEntry[] = [{ path: "/about" }]
+    const urls = buildSitemapUrls(entries, config)
+
+    expect(urls).toHaveLength(2)
+    expect(urls[0]!.loc).toBe("https://example.com/about")
+    expect(urls[1]!.loc).toBe("https://example.com/pt/about")
+  })
+
+  it("includes alternates for multi-locale entries", () => {
+    const entries: SeoEntry[] = [{ path: "/about" }]
+    const urls = buildSitemapUrls(entries, config)
+
+    // Default locale URL should have x-default alternate
+    const defaultUrl = urls.find((u) => u.loc === "https://example.com/about")
+    expect(defaultUrl?.alternates).toHaveLength(2)
+    expect(defaultUrl?.alternates?.[0]!.hreflang).toBe("pt-BR")
+    expect(defaultUrl?.alternates?.[0]!.href).toBe("https://example.com/pt/about")
+    expect(defaultUrl?.alternates?.[1]!.hreflang).toBe("x-default")
+    expect(defaultUrl?.alternates?.[1]!.href).toBe("https://example.com/about")
+
+    // Non-default locale URL should have only the other locale as alternate
+    const ptUrl = urls.find((u) => u.loc === "https://example.com/pt/about")
+    expect(ptUrl?.alternates).toHaveLength(1)
+    expect(ptUrl?.alternates?.[0]!.hreflang).toBe("en-US")
+    expect(ptUrl?.alternates?.[0]!.href).toBe("https://example.com/about")
+  })
+
+  it("handles prefixDefaultLocale option", () => {
+    const configWithPrefix: LocaleConfig = {
+      ...config,
+      prefixDefaultLocale: true
+    }
+    const entries: SeoEntry[] = [{ path: "/about" }]
+    const urls = buildSitemapUrls(entries, configWithPrefix)
+
+    expect(urls[0]!.loc).toBe("https://example.com/en/about")
+    expect(urls[1]!.loc).toBe("https://example.com/pt/about")
+  })
+
+  it("handles trailingSlash option", () => {
+    const configWithSlash: LocaleConfig = {
+      ...config,
+      trailingSlash: "always"
+    }
+    const entries: SeoEntry[] = [{ path: "/about" }]
+    const urls = buildSitemapUrls(entries, configWithSlash)
+
+    expect(urls[0]!.loc).toBe("https://example.com/about/")
+    expect(urls[1]!.loc).toBe("https://example.com/pt/about/")
+  })
+
+  it("includes lastmod when provided", () => {
+    const date = new Date("2024-01-01")
+    const entries: SeoEntry[] = [{ path: "/about", lastmod: date }]
+    const urls = buildSitemapUrls(entries, config)
+
+    expect(urls[0]!.lastmod).toBe(date.toISOString())
+  })
+
+  it("includes changefreq and priority when provided", () => {
+    const entries: SeoEntry[] = [{ path: "/about", changefreq: "weekly", priority: 0.8 }]
+    const urls = buildSitemapUrls(entries, config)
+
+    expect(urls[0]!.changefreq).toBe("weekly")
+    expect(urls[0]!.priority).toBe(0.8)
+  })
+
+  it("restricts to specified locales", () => {
+    const entries: SeoEntry[] = [{ path: "/about", locales: ["en"] }]
+    const urls = buildSitemapUrls(entries, config)
+
+    expect(urls).toHaveLength(1)
+    expect(urls[0]!.loc).toBe("https://example.com/about")
+  })
+})
+
+describe("buildSitemapXml", () => {
+  it("generates valid XML for URLs", () => {
+    const urls = [
+      {
+        loc: "https://example.com/about",
+        lastmod: "2024-01-01T00:00:00.000Z",
+        changefreq: "weekly" as const,
+        priority: 0.8
+      }
+    ]
+
+    const xml = buildSitemapXml(urls)
+
+    expect(xml).toContain('<?xml version="1.0" encoding="UTF-8"?>')
+    expect(xml).toContain("<urlset")
+    expect(xml).toContain("https://example.com/about")
+    expect(xml).toContain("<lastmod>2024-01-01T00:00:00.000Z</lastmod>")
+    expect(xml).toContain("<changefreq>weekly</changefreq>")
+    expect(xml).toContain("<priority>0.8</priority>")
+  })
+
+  it("includes alternates in XML", () => {
+    const urls = [
+      {
+        loc: "https://example.com/about",
+        alternates: [
+          { hreflang: "pt-BR", href: "https://example.com/pt/about" },
+          { hreflang: "x-default", href: "https://example.com/about" }
+        ]
+      }
+    ]
+
+    const xml = buildSitemapXml(urls)
+
+    expect(xml).toContain("xhtml:link")
+    expect(xml).toContain('hreflang="pt-BR"')
+    expect(xml).toContain('hreflang="x-default"')
+  })
+
+  it("escapes XML special characters", () => {
+    const urls = [
+      {
+        loc: "https://example.com/about?query=test&amp;other=value"
+      }
+    ]
+
+    const xml = buildSitemapXml(urls)
+
+    expect(xml).toContain("&amp;")
+  })
+})
+
+describe("buildSitemapIndexXml", () => {
+  it("generates valid sitemap index XML", () => {
+    const sitemaps = ["https://example.com/sitemap-0.xml", "https://example.com/sitemap-1.xml"]
+
+    const xml = buildSitemapIndexXml(sitemaps)
+
+    expect(xml).toContain('<?xml version="1.0" encoding="UTF-8"?>')
+    expect(xml).toContain("<sitemapindex")
+    expect(xml).toContain("https://example.com/sitemap-0.xml")
+    expect(xml).toContain("https://example.com/sitemap-1.xml")
+  })
+})
+
+describe("chunkSitemapUrls", () => {
+  it("chunks URLs at default limit", () => {
+    const urls = Array.from({ length: 50000 }, (_, i) => ({
+      loc: `https://example.com/page-${i}`
+    }))
+
+    const chunks = chunkSitemapUrls(urls)
+
+    expect(chunks).toHaveLength(2)
+    expect(chunks[0]).toHaveLength(45000)
+    expect(chunks[1]).toHaveLength(5000)
+  })
+
+  it("handles custom limit", () => {
+    const urls = Array.from({ length: 100 }, (_, i) => ({
+      loc: `https://example.com/page-${i}`
+    }))
+
+    const chunks = chunkSitemapUrls(urls, 25)
+
+    expect(chunks).toHaveLength(4)
+    expect(chunks[0]).toHaveLength(25)
+  })
+
+  it("returns single chunk for small arrays", () => {
+    const urls = [{ loc: "https://example.com/page-1" }, { loc: "https://example.com/page-2" }]
+
+    const chunks = chunkSitemapUrls(urls)
+
+    expect(chunks).toHaveLength(1)
+    expect(chunks[0]).toHaveLength(2)
+  })
+})

package/src/sitemap.ts

@@ -0,0 +1,166 @@
+import type { LocaleConfig, SeoEntry, SitemapUrl } from "./types.js"
+
+/**
+ * Build fully-resolved sitemap URLs from entries and locale config
+ */
+export function buildSitemapUrls(entries: SeoEntry[], config: LocaleConfig): SitemapUrl[] {
+  const urls: SitemapUrl[] = []
+  const { site, locales, defaultLocale, prefixDefaultLocale, trailingSlash } = config
+
+  for (const entry of entries) {
+    const entryLocales =
+      entry.locales && entry.locales.length > 0 ? entry.locales : Object.keys(locales)
+
+    const entryUrls: SitemapUrl[] = []
+
+    for (const locale of entryLocales) {
+      const isDefault = locale === defaultLocale
+      const localePrefix = !isDefault || prefixDefaultLocale ? `/${locale}` : ""
+
+      let path = entry.path
+      if (trailingSlash === "always" && !path.endsWith("/")) {
+        path += "/"
+      } else if (trailingSlash === "never" && path.endsWith("/")) {
+        path = path.replace(/\/$/, "")
+      }
+
+      const loc = `${site}${localePrefix}${path}`
+
+      const item: SitemapUrl = { loc }
+      if (entry.lastmod) {
+        item.lastmod = entry.lastmod.toISOString()
+      }
+      if (entry.changefreq) {
+        item.changefreq = entry.changefreq
+      }
+      if (entry.priority !== undefined) {
+        item.priority = entry.priority
+      }
+      entryUrls.push(item)
+    }
+
+    // Add alternates if multiple locales
+    if (entryUrls.length > 1) {
+      const defaultUrl = entryUrls.find(
+        (u) => u.loc === `${site}${prefixDefaultLocale ? `/${defaultLocale}` : ""}${entry.path}`
+      )
+
+      for (const url of entryUrls) {
+        url.alternates = entryUrls
+          .filter((u) => u.loc !== url.loc)
+          .map((u) => ({
+            hreflang: extractHreflang(u.loc, locales, defaultLocale),
+            href: u.loc
+          }))
+
+        // Add x-default pointing to default locale
+        // x-default should be on the default URL itself, pointing to itself
+        if (defaultUrl && url.loc === defaultUrl.loc) {
+          url.alternates.push({
+            hreflang: "x-default",
+            href: defaultUrl.loc
+          })
+        }
+      }
+    }
+
+    urls.push(...entryUrls)
+  }
+
+  return urls
+}
+
+/**
+ * Build sitemap XML from resolved URLs
+ */
+export function buildSitemapXml(urls: SitemapUrl[]): string {
+  const urlElements = urls
+    .map((url) => {
+      let xml = `  <url>\n    <loc>${escapeXml(url.loc)}</loc>`
+
+      if (url.lastmod) {
+        xml += `\n    <lastmod>${url.lastmod}</lastmod>`
+      }
+
+      if (url.changefreq) {
+        xml += `\n    <changefreq>${url.changefreq}</changefreq>`
+      }
+
+      if (url.priority !== undefined) {
+        xml += `\n    <priority>${url.priority.toFixed(1)}</priority>`
+      }
+
+      if (url.alternates && url.alternates.length > 0) {
+        for (const alt of url.alternates) {
+          xml += `\n    <xhtml:link rel="alternate" hreflang="${alt.hreflang}" href="${escapeXml(alt.href)}" />`
+        }
+      }
+
+      xml += "\n  </url>"
+      return xml
+    })
+    .join("\n")
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
+${urlElements}
+</urlset>`
+}
+
+/**
+ * Build sitemap index XML from sitemap URLs
+ */
+export function buildSitemapIndexXml(sitemapUrls: string[]): string {
+  const sitemapElements = sitemapUrls
+    .map(
+      (url) => `  <sitemap>
+    <loc>${escapeXml(url)}</loc>
+  </sitemap>`
+    )
+    .join("\n")
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${sitemapElements}
+</sitemapindex>`
+}
+
+/**
+ * Chunk sitemap URLs into multiple sitemaps (max 50k URLs per sitemap)
+ */
+export function chunkSitemapUrls(urls: SitemapUrl[], limit: number = 45000): SitemapUrl[][] {
+  const chunks: SitemapUrl[][] = []
+  for (let i = 0; i < urls.length; i += limit) {
+    chunks.push(urls.slice(i, i + limit))
+  }
+  return chunks
+}
+
+/**
+ * Extract hreflang from a URL based on locale config
+ */
+function extractHreflang(
+  url: string,
+  locales: Record<string, string>,
+  defaultLocale: string
+): string {
+  for (const [segment, hreflang] of Object.entries(locales)) {
+    if (url.includes(`/${segment}/`) || url.endsWith(`/${segment}`)) {
+      return hreflang
+    }
+  }
+  // Default to the first locale's hreflang if no match
+  return locales[defaultLocale] || "en"
+}
+
+/**
+ * Escape XML special characters
+ */
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;")
+}

package/src/types.ts

@@ -0,0 +1,219 @@
+/**
+ * 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[]
+}
+
+/**
+ * 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
+  }
+}
+
+/**
+ * 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 }>
+  /**
+   * 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
+}