@rimelight/seo 0.0.1 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimelight/seo",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "private": false,
   "description": "Rimelight Entertainment's SEO Package",
   "homepage": "https://rimelight.com/docs",
@@ -16,26 +16,36 @@
     "url": "git+https://github.com/Rimelight-Entertainment/rimelight.git"
   },
   "files": [
-    "src"
+    "dist",
+    "src/components"
   ],
   "type": "module",
   "exports": {
-    ".": "./src/index.ts",
-    "./types": "./src/types.ts",
-    "./sitemap": "./src/sitemap.ts",
-    "./robots": "./src/robots.ts",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/types.mjs"
+    },
+    "./sitemap": {
+      "types": "./dist/sitemap.d.mts",
+      "import": "./dist/sitemap.mjs"
+    },
+    "./robots": {
+      "types": "./dist/robots.d.mts",
+      "import": "./dist/robots.mjs"
+    },
     "./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",
+    "@rimelight/config": "0.0.4",
+    "astro": "7.3.1",
     "typescript": "6.0.3"
   },
   "peerDependencies": {
@@ -44,5 +54,8 @@
   "engines": {
     "node": ">=26.7.0"
   },
-  "packageManager": "pnpm@11.22.0"
-}
+  "scripts": {
+    "build": "vp pack",
+    "check": "vp check --fix && astro check"
+  }
+}

package/src/components/AgentDirective.astro

@@ -0,0 +1,25 @@
+---
+interface Props {
+  /** Absolute or site-relative URL for this page's markdown version. */
+  markdownUrl?: string | undefined
+  /** Absolute or site-relative URL for the top-level llms.txt index. */
+  llmsUrl?: string | undefined
+  class?: string | undefined
+}
+
+const {
+  markdownUrl,
+  llmsUrl = "/llms.txt",
+  class: className = "sr-only"
+} = Astro.props
+---
+
+<aside class={className} data-ai-agent-directive>
+  This page is available in Markdown format. Markdown is recommended for AI and agentic consumption.
+  {markdownUrl && (
+    <>
+      See <a href={markdownUrl}>{markdownUrl}</a> for this page, or{" "}
+    </>
+  )}
+  <a href={llmsUrl}>{llmsUrl}</a> for the full documentation and content index.
+</aside>

package/src/components/SEOHead.astro

@@ -7,6 +7,7 @@ import {
   buildRobotsMetaContent,
   buildWebSiteSchema
 } from "../meta.js"
+import { buildArticleSchema, buildBreadcrumbSchema } from "../schema.js"
 
 const {
   title,
@@ -23,6 +24,10 @@ const {
   charset = 'utf-8',
   viewport = 'width=device-width, initial-scale=1',
   rssFeed,
+  articleSchema,
+  breadcrumbs,
+  markdownUrl,
+  versionAlternates = [],
 } = Astro.props as HeadProps
 
 // Resolve defaults from config if available
@@ -85,6 +90,12 @@ const robotsContent = buildRobotsMetaContent({
   <link rel="alternate" hreflang={alt.hreflang} href={alt.href} />
 ))}
 
+<!-- Agent & Version Alternates -->
+{markdownUrl && <link rel="alternate" type="text/markdown" href={markdownUrl} title="Markdown Format" />}
+{versionAlternates.map((alt) => (
+  <link rel="alternate" data-version={alt.version} href={alt.href} />
+))}
+
 <!-- Open Graph / Facebook -->
 <meta property="og:type" content={ogType} />
 <meta property="og:locale" content={ogLocale} />
@@ -122,3 +133,16 @@ const robotsContent = buildRobotsMetaContent({
     buildWebSiteSchema(config, Astro.site?.toString())
   )} />
 )}
+
+{articleSchema && (
+  <script type="application/ld+json" is:inline set:html={JSON.stringify(
+    buildArticleSchema(articleSchema)
+  )} />
+)}
+
+{breadcrumbs && breadcrumbs.length > 0 && (
+  <script type="application/ld+json" is:inline set:html={JSON.stringify(
+    buildBreadcrumbSchema(breadcrumbs)
+  )} />
+)}
+

package/src/env.d.ts

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

package/src/index.ts

@@ -1,30 +0,0 @@
-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

@@ -1,110 +0,0 @@
-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

@@ -1,70 +0,0 @@
-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

@@ -1,75 +0,0 @@
-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

@@ -1,59 +0,0 @@
-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

@@ -1,191 +0,0 @@
-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)
-  })
-})