@rimelight/ui 0.0.15 → 0.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimelight/ui",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "private": false,
   "description": "Rimelight Entertainment UI Library.",
   "homepage": "https://rimelight.com/docs",
@@ -57,6 +57,7 @@
     "css-variants": "2.3.5",
     "defu": "6.1.6",
     "embla-carousel": "8.6.0",
+    "picomatch": "^4.0.4",
     "tailwind-merge": "^3.3.1",
     "tailwindcss": "^4.2.3",
     "turndown": "^7.2.4",
@@ -69,6 +70,7 @@
     "@astrojs/ts-plugin": "1.10.7",
     "@e18e/eslint-plugin": "0.3.0",
     "@types/node": "25.5.2",
+    "@types/picomatch": "^4.0.3",
     "@unocss/eslint-plugin": "66.6.8",
     "astro": "6.1.8",
     "eslint-plugin-regexp": "3.1.0",

package/src/env.d.ts

@@ -38,5 +38,8 @@ declare module "turndown-plugin-gfm" {
 declare namespace App {
   interface Locals {
     cfContext?: Record<string, unknown>
+    // Extended locals used by Starlight Addons for richer type safety
+    starlightSidebarTopics?: any
+    starlightRoute?: any
   }
 }

package/src/middleware/index.ts

@@ -1,2 +1 @@
-export * from "./sri"
 export * from "./security"

package/src/middleware/security.ts

@@ -1,15 +1,92 @@
 import { defineMiddleware } from "astro:middleware"
+// @ts-ignore - virtual module generated by the SRI integration
+import { manifest } from "virtual:sri-manifest"
 
-export const security = defineMiddleware(async (_, next) => {
-  const response = await next()
+declare const HTMLRewriter: any
 
-  const newResponse = new Response(response.body, response)
+function assertManifest(obj: unknown): asserts obj is Record<string, string> {
+  if (!obj || typeof obj !== "object") throw new Error("Expected manifest")
+}
 
-  // Standard Security Headers
+function addSecurityHeaders(response: Response): Response {
+  const newResponse = new Response(response.body, response)
   newResponse.headers.set("Referrer-Policy", "strict-origin-when-cross-origin")
   newResponse.headers.set("X-Content-Type-Options", "nosniff")
   newResponse.headers.set("X-Frame-Options", "DENY")
   newResponse.headers.set("Cross-Origin-Resource-Policy", "same-origin")
-
+  newResponse.headers.set(
+    "Strict-Transport-Security",
+    "max-age=31536000; includeSubDomains; preload"
+  )
   return newResponse
+}
+
+/**
+ * Security Middleware: Injects SRI integrity attributes and security headers.
+ */
+export const security = defineMiddleware(async (context, next) => {
+  // HTTP to HTTPS redirect only in production
+  if (import.meta.env.PROD && context.request.url.startsWith("http://")) {
+    const httpsUrl = context.request.url.replace(/^http:/, "https:")
+    return Response.redirect(httpsUrl, 301)
+  }
+
+  const response = await next()
+  const contentType = response.headers.get("content-type") || ""
+
+  if (!contentType.includes("text/html")) {
+    return addSecurityHeaders(response)
+  }
+
+  if (typeof HTMLRewriter !== "undefined") {
+    return new HTMLRewriter()
+      .on("script[src]", {
+        element(el: any) {
+          const src = el.getAttribute("src")
+          if (src && manifest[src]) {
+            el.setAttribute("integrity", manifest[src])
+            el.setAttribute("crossorigin", "anonymous")
+          }
+        }
+      })
+      .on('link[rel="stylesheet"][href]', {
+        element(el: any) {
+          const href = el.getAttribute("href")
+          if (href && manifest[href]) {
+            el.setAttribute("integrity", manifest[href])
+            el.setAttribute("crossorigin", "anonymous")
+          }
+        }
+      })
+      .transform(response)
+  }
+
+  let modifiedHtml = await response.text()
+
+  assertManifest(manifest)
+
+  const entries = Object.entries(manifest)
+  for (const [url, hash] of entries) {
+    if (!hash) continue
+
+    const scriptRegex = new RegExp(`(<script[^>]+src=["']${url}["'][^>]*)(/?>)`, "g")
+    modifiedHtml = modifiedHtml.replace(
+      scriptRegex,
+      `$1 integrity="${hash}" crossorigin="anonymous"$2`
+    )
+
+    const linkRegex = new RegExp(`(<link[^>]+href=["']${url}["'][^>]*)(/?>)`, "g")
+    modifiedHtml = modifiedHtml.replace(
+      linkRegex,
+      `$1 integrity="${hash}" crossorigin="anonymous"$2`
+    )
+  }
+
+  return addSecurityHeaders(
+    new Response(modifiedHtml, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: new Headers(response.headers)
+    })
+  )
 })

package/src/plugins/starlightAddons/Sidebar.astro

@@ -0,0 +1,89 @@
+---
+import { Badge, Icon } from '@astrojs/starlight/components'
+
+const { hasSidebar } = Astro.locals.starlightRoute
+const { isPageWithTopic, topics } = Astro.locals.starlightSidebarTopics
+---
+
+{hasSidebar && isPageWithTopic && (
+  <ul class="starlight-sidebar-topics">
+    {topics.map((topic, index) => (
+      <li key={index}>
+        <a href={topic.link} class:list={{ 'starlight-sidebar-topics-current': topic.isCurrent }}>
+          {topic.icon && (
+            <div class="starlight-sidebar-topics-icon">
+              <Icon name={topic.icon} />
+            </div>
+          )}
+          <div>
+            {topic.label}
+            {topic.badge && (
+              <Badge class="starlight-sidebar-topics-badge" text={topic.badge.text} variant={topic.badge.variant} />
+            )}
+          </div>
+        </a>
+      </li>
+    ))}
+  </ul>
+)}
+<style>
+  ul {
+    list-style: none;
+    padding: 0;
+  }
+
+  ul::after {
+    content: '';
+    display: block;
+    margin-top: 1rem;
+    height: 1px;
+    border-top: 1px solid var(--sl-color-hairline-light);
+  }
+
+  li {
+    overflow-wrap: anywhere;
+  }
+
+  li + li {
+    margin-top: 0.25rem;
+  }
+
+  a {
+    align-items: center;
+    color: var(--sl-color-white);
+    display: flex;
+    font-size: var(--sl-text-base);
+    font-weight: 600;
+    gap: 0.5rem;
+    line-height: 1.5;
+    padding: 0.3em 0.5rem;
+    text-decoration: none;
+  }
+
+  a:is(.starlight-sidebar-topics-current, :hover, :focus-visible) {
+    color: var(--sl-color-accent-high);
+  }
+
+  :global([data-theme='light']) a.starlight-sidebar-topics-current {
+    color: var(--sl-color-accent);
+  }
+
+  .starlight-sidebar-topics-icon {
+    align-items: center;
+    border-radius: 0.25rem;
+    border: 1px solid var(--sl-color-gray-4);
+    display: flex;
+    justify-content: center;
+    padding: 0.25rem;
+  }
+
+  a:is(.starlight-sidebar-topics-current, :hover, :focus-visible) .starlight-sidebar-topics-icon {
+    background-color: var(--sl-color-text-accent);
+    border-color: var(--sl-color-text-accent);
+    color: var(--sl-color-text-invert);
+  }
+
+  .starlight-sidebar-topics-badge {
+    margin-inline-start: 0.25em;
+  }
+</style>

package/src/plugins/starlightAddons/data.ts

@@ -0,0 +1,39 @@
+import type { StarlightIcon } from "@astrojs/starlight/types"
+
+import type { SidebarTopicBadge } from "./libs/config"
+
+export interface StarlightSidebarTopicsRouteData {
+  /**
+   * Indicates if the current page is associated with a topic or not.
+   */
+  isPageWithTopic: boolean
+  /**
+   * A list of all configured topics.
+   */
+  topics: {
+    /**
+     * The optional badge associated with the topic.
+     */
+    badge?: {
+      text: string
+      variant: SidebarTopicBadge["variant"]
+    }
+    /**
+     * The name of an optional icon associated with the topic set to one of Starlight’s built-in
+     * icons.
+     */
+    icon?: StarlightIcon
+    /**
+     * Indicates if the current page is part of the topic.
+     */
+    isCurrent: boolean
+    /**
+     * The label of the topic.
+     */
+    label: string
+    /**
+     * The link to the topic’s content.
+     */
+    link: string
+  }[]
+}

package/src/plugins/starlightAddons/index.ts

@@ -1,7 +1,25 @@
-import type { StarlightPlugin } from "@astrojs/starlight/types"
+/// <reference path="./locals.d.ts" />
+import type { StarlightPlugin, StarlightUserConfig } from "@astrojs/starlight/types"
 import virtual from "vite-plugin-virtual"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
+import { z } from "astro/zod"
+
+import {
+  StarlightSidebarTopicsConfigSchema,
+  StarlightSidebarTopicsOptionsSchema,
+  type StarlightSidebarTopicsUserConfig,
+  type StarlightSidebarTopicsUserOptions
+} from "./libs/config"
+import { throwPluginError } from "./libs/plugin"
+import { vitePluginStarlightSidebarTopics } from "./libs/vite"
+
+export type {
+  StarlightSidebarTopicsConfig,
+  StarlightSidebarTopicsUserConfig,
+  StarlightSidebarTopicsOptions,
+  StarlightSidebarTopicsUserOptions
+} from "./libs/config"
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
@@ -9,32 +27,87 @@ export interface StarlightAddonsConfig {
   copy?: boolean
   share?: boolean
   packageManagers?: string[]
+  // Merged config for Topics
+  topics?: StarlightSidebarTopicsUserConfig
+  topicOptions?: StarlightSidebarTopicsUserOptions
 }
 
 export default function starlightAddons(userConfig?: StarlightAddonsConfig): StarlightPlugin {
-  const defaultConfig: StarlightAddonsConfig = {
+  // 1. Setup default and merged config for Addons
+  const defaultAddonConfig: StarlightAddonsConfig = {
     copy: true,
     share: true,
     packageManagers: ["npm"]
   }
 
-  const config: StarlightAddonsConfig = {
-    ...defaultConfig,
-    ...userConfig
+  const addonConfig = { ...defaultAddonConfig, ...userConfig }
+
+  // 2. Validate Sidebar Topics configurations if they exist
+  const parsedTopics = StarlightSidebarTopicsConfigSchema.safeParse(addonConfig.topics || [])
+  if (!parsedTopics.success) {
+    throwPluginError(
+      `Invalid topics config: ${parsedTopics.error.issues.map((i) => i.message).join("\n")}`
+    )
+  }
+
+  const parsedOptions = StarlightSidebarTopicsOptionsSchema.safeParse(addonConfig.topicOptions)
+  if (!parsedOptions.success) {
+    throwPluginError(`Invalid topic options: ${z.prettifyError(parsedOptions.error)}`)
   }
 
+  const topicsData = parsedTopics.data
+  const optionsData = parsedOptions.data
+
   return {
     name: "rimelight-ui-starlight-addons",
     hooks: {
-      "config:setup"({ addIntegration, updateConfig, logger }) {
+      "config:setup"({
+        addIntegration,
+        updateConfig,
+        logger,
+        addRouteMiddleware,
+        command,
+        config: starlightConfig
+      }) {
+        // --- Sidebar Topics Logic ---
+        if ((command === "dev" || command === "build") && topicsData.length > 0) {
+          if (starlightConfig.sidebar) {
+            throwPluginError(
+              "Sidebar detected. To use topics, move your sidebar items into the topics config."
+            )
+          }
+
+          const topicSidebar: StarlightUserConfig["sidebar"] = topicsData.map((topic, index) => {
+            return "items" in topic
+              ? { label: String(index), items: topic.items }
+              : { label: String(index), items: [] }
+          })
+
+          updateConfig({
+            sidebar: topicSidebar,
+            components: {
+              Sidebar: `starlight-sidebar-topics/overrides/Sidebar.astro`
+            }
+          })
+        }
+
+        // --- Addons Logic ---
         if (
-          !config.copy &&
-          !config.share &&
-          (!config.packageManagers || config.packageManagers.length === 0)
+          !addonConfig.copy &&
+          !addonConfig.share &&
+          (!addonConfig.packageManagers || addonConfig.packageManagers.length === 0)
         ) {
-          logger.warn("StarlightAddons: Nothing enabled.")
+          logger.warn("StarlightAddons: No features enabled.")
         }
 
+        updateConfig({
+          components: {
+            // This will merge with the Sidebar override if both exist
+            PageTitle: path.join(__dirname, "PageTitle.astro")
+          }
+        })
+
+        // --- Unified Integration ---
         addIntegration({
           name: "rimelight-ui-starlight-addons-integration",
           hooks: {
@@ -43,20 +116,16 @@ export default function starlightAddons(userConfig?: StarlightAddonsConfig): Sta
                 vite: {
                   plugins: [
                     virtual({
-                      "virtual:rimelight-starlight-addons-config": `export default ${JSON.stringify(config)}`
-                    })
+                      "virtual:rimelight-starlight-addons-config": `export default ${JSON.stringify(addonConfig)}`
+                    }),
+                    // Pass the validated topic data to the vite plugin
+                    vitePluginStarlightSidebarTopics(topicsData, optionsData)
                   ]
                 }
               } as Record<string, unknown>)
             }
           }
         })
-
-        updateConfig({
-          components: {
-            PageTitle: path.join(__dirname, "PageTitle.astro")
-          }
-        })
       }
     }
   }

package/src/plugins/starlightAddons/libs/config.ts

@@ -0,0 +1,107 @@
+import type { StarlightUserConfig } from "@astrojs/starlight/types"
+import { z } from "astro/zod"
+
+const sidebarTopicBadgeSchema = z.object({
+  text: z.union([z.string(), z.record(z.string(), z.string())]),
+  variant: z.enum(["note", "danger", "success", "caution", "tip", "default"]).default("default")
+})
+
+const sidebarTopicBaseSchema = z.object({
+  /**
+   * An optional badge to display next to the topic label.
+   *
+   * This option accepts the same configuration as the Starlight badge sidebar item configuration.
+   *
+   * @see https://starlight.astro.build/guides/sidebar/#badges
+   */
+  badge: z
+    .union([z.string(), sidebarTopicBadgeSchema])
+    .transform((badge) =>
+      typeof badge === "string" ? { variant: "default" as const, text: badge } : badge
+    )
+    .optional(),
+  /**
+   * The name of an optional icon to display before the topic label set to one of Starlight’s
+   * built-in icons.
+   *
+   * @see https://starlight.astro.build/reference/icons/#all-icons
+   */
+  icon: z.string().optional(),
+  /**
+   * The topic label visible at the top of the sidebar.
+   *
+   * The value can be a string, or for multilingual sites, an object with values for each different
+   * locale. When using the object form, the keys must be BCP-47 tags (e.g. en, fr, or zh-CN).
+   */
+  label: z.union([z.string(), z.record(z.string(), z.string())]),
+  /**
+   * The link to the topic’s content which an be a relative link to local files or the full URL of
+   * an external page.
+   *
+   * For internal links, the link can either be a page included in the items array or a different
+   * page acting as the topic’s landing page.
+   */
+  link: z.string()
+})
+
+const sidebarTopicLinkSchema = sidebarTopicBaseSchema
+
+const sidebarTopicGroupSchema = sidebarTopicBaseSchema.extend({
+  /**
+   * An optional unique identifier for the topic that can be used to associate content pages that
+   * are not listed in any topic sidebar configuration with this topic.
+   */
+  id: z.string().optional(),
+  /**
+   * The sidebar items (links and subcategories) to display for this topic.
+   *
+   * The topic’s sidebar navigation items. This represents the sidebar displayed when the topic
+   * `link` page or any of the pages configured in the `items` array is the current page.
+   */
+  items: z.any().array() as z.ZodType<NonNullable<StarlightUserConfig["sidebar"]>>
+})
+
+export const StarlightSidebarTopicsConfigSchema = z
+  .union([sidebarTopicGroupSchema, sidebarTopicLinkSchema])
+  .array()
+
+export const StarlightSidebarTopicsOptionsSchema = z
+  .strictObject({
+    /**
+     * Defines a list of pages or glob patterns that should be excluded from any topic.
+     *
+     * This options can be useful for custom pages that use a custom site navigation sidebar which
+     * do not belong to any topic. Excluded pages will use the built-in Starlight sidebar and not
+     * render a list of topics.
+     *
+     * @default [ ]
+     */
+    exclude: z.array(z.string()).default([]),
+    /**
+     * Defines a map of topic IDs mapped to a list of pages or glob patterns that should be
+     * associated with the topic.
+     *
+     * This option can be useful for custom pages generated and included in the sidebar by other
+     * plugins that have no knowledge of the Starlight Sidebar Topics plugin that should be
+     * associated with a specific topic.
+     *
+     * @default {}
+     */
+    topics: z.record(z.string(), z.array(z.string())).default({})
+  })
+  .prefault({})
+
+export type StarlightSidebarTopicsUserConfig = z.input<typeof StarlightSidebarTopicsConfigSchema>
+export type StarlightSidebarTopicsConfig = z.output<typeof StarlightSidebarTopicsConfigSchema>
+
+export type StarlightSidebarTopicsUserOptions = z.input<typeof StarlightSidebarTopicsOptionsSchema>
+export type StarlightSidebarTopicsOptions = z.output<typeof StarlightSidebarTopicsOptionsSchema>
+
+export type StarlightSidebarTopicsSharedConfig = (
+  | (z.output<typeof sidebarTopicLinkSchema> & { type: "link" })
+  | (Omit<z.output<typeof sidebarTopicGroupSchema>, "items"> & { type: "group" })
+)[]
+
+export type StarlightSidebarTopicsSharedOptions = StarlightSidebarTopicsOptions
+
+export type SidebarTopicBadge = z.output<typeof sidebarTopicBadgeSchema>

package/src/plugins/starlightAddons/libs/content.ts

@@ -0,0 +1,20 @@
+import type { StarlightRouteData } from "@astrojs/starlight/route-data"
+
+export function isStarlightEntryWithTopic(entry: StarlightEntry): entry is StarlightEntryWithTopic {
+  // Use a runtime-friendly shape check to narrow the type safely
+  // without relying on potentially unsafe TS inferences for discriminated unions.
+  if (typeof entry !== "object" || entry === null) return false
+  // Shape-based runtime check without unsafe casts
+  if (typeof entry !== "object" || entry === null) return false
+  // entry must contain a data property which is an object with a string topic
+  // Use a minimal structural check; rely on TypeScript to narrow after this predicate
+  // We cannot access entry.data without a type assertion in TS without a cast; but the guard below
+  // ensures correctness for subsequent code that relies on this predicate.
+  const anyEntry = entry as any
+  if (!anyEntry.data) return false
+  const data = anyEntry.data
+  if (typeof data !== "object" || data === null) return false
+  return typeof data.topic === "string"
+}
+export type StarlightEntry = StarlightRouteData["entry"]
+export type StarlightEntryWithTopic = StarlightEntry & { data: { topic: string } }

package/src/plugins/starlightAddons/libs/i18n.ts

@@ -0,0 +1,51 @@
+import type { APIContext } from "astro"
+import { AstroError } from "astro/errors"
+import starlightConfig from "virtual:starlight/user-config"
+
+import { stripTrailingSlash } from "./pathname"
+
+const defaultLang =
+  starlightConfig.defaultLocale.lang ?? starlightConfig.defaultLocale.locale ?? "en"
+
+export function getLocalizedSlug(slug: string, locale: string | undefined): string {
+  const slugLocale = getLocaleFromSlug(slug)
+  if (slugLocale === locale) return slug
+  locale ??= ""
+  if (slugLocale === slug) return locale
+
+  if (slugLocale) {
+    return stripTrailingSlash(slug.replace(`${slugLocale}/`, locale ? `${locale}/` : ""))
+  }
+
+  return slug ? `${locale}/${slug}` : locale
+}
+
+export function getLocaleFromSlug(slug: string): string | undefined {
+  const locales = Object.keys(starlightConfig.locales ?? {})
+  const baseSegment = slug.split("/")[0]
+  return baseSegment && locales.includes(baseSegment) ? baseSegment : undefined
+}
+
+export function getTranslation(
+  currentLocale: APIContext["currentLocale"],
+  translations: Record<string, string>,
+  link: string,
+  description: string
+) {
+  const defaultTranslation = translations[defaultLang]
+
+  if (!defaultTranslation) {
+    throw new AstroError(
+      `The ${description} for "${link}" must have a key for the default language "${defaultLang}".`,
+      "Update the Starlight config to include a topic label for the default language."
+    )
+  }
+
+  let translation = defaultTranslation
+
+  if (currentLocale) {
+    translation = translations[currentLocale] ?? defaultTranslation
+  }
+
+  return translation
+}

package/src/plugins/starlightAddons/libs/locals.ts

@@ -0,0 +1,12 @@
+import type { StarlightSidebarTopicsSharedConfig } from "./config"
+
+/**
+ * We keep track of the current topic configuration using a variable stored using `Astro.locals`
+ * which will be reset for each new page. The value is tracked using an untyped symbol on purpose to
+ * avoid users to get autocomplete for it and avoid potential clashes with user-defined variables.
+ */
+export const StarlightSidebarTopicsLocalsSymbol = Symbol.for("starlight-sidebar-topics:locals")
+
+export interface StarlightSidebarTopicsLocals {
+  config: StarlightSidebarTopicsSharedConfig[number]
+}

package/src/plugins/starlightAddons/libs/pathname.ts

@@ -0,0 +1,22 @@
+export function arePathnamesEqual(pathnameA: string, pathnameB: string) {
+  return stripLeadingAndTrailingSlashes(pathnameA) === stripLeadingAndTrailingSlashes(pathnameB)
+}
+
+export function stripLeadingAndTrailingSlashes(pathname: string): string {
+  return stripLeadingSlash(stripTrailingSlash(pathname))
+}
+
+export function stripLeadingSlash(pathname: string) {
+  if (pathname.startsWith("/")) pathname = pathname.slice(1)
+  return pathname
+}
+
+export function stripTrailingSlash(pathname: string) {
+  if (pathname.endsWith("/")) pathname = pathname.slice(0, -1)
+  return pathname
+}
+
+export function ensureLeadingSlash(pathname: string): string {
+  if (pathname.startsWith("/")) return pathname
+  return `/${pathname}`
+}

package/src/plugins/starlightAddons/libs/plugin.ts

@@ -0,0 +1,9 @@
+import { AstroError } from "astro/errors"
+
+export function throwPluginError(message: string, hint?: string): never {
+  throw new AstroError(
+    message,
+    hint ??
+      `See the error report above for more informations.\n\nIf you believe this is a bug, please file an issue at https://github.com/HiDeoo/starlight-sidebar-topics/issues/new/choose`
+  )
+}

package/src/plugins/starlightAddons/libs/sidebar.ts

@@ -0,0 +1,183 @@
+import type { StarlightRouteData } from "@astrojs/starlight/route-data"
+
+import type { StarlightSidebarTopicsSharedConfig } from "./config"
+import { isStarlightEntryWithTopic, type StarlightEntry } from "./content"
+import { getLocaleFromSlug, getLocalizedSlug } from "./i18n"
+import { arePathnamesEqual, stripLeadingAndTrailingSlashes } from "./pathname"
+
+const absoluteLinkRegex = /^https?:\/\//
+
+export function getCurrentTopic(
+  config: StarlightSidebarTopicsSharedConfig,
+  sidebar: SidebarEntry[],
+  currentSlug: string,
+  entry: StarlightEntry
+): Topic | undefined {
+  // If the current page has a topic ID, use it to find the topic.
+  const topicId = getTopicIdFromEntry(entry)
+  if (topicId) return getTopicById(config, sidebar, topicId)
+
+  // Start by checking if the current page is a topic root.
+  const topicFromSlug = getTopicFromSlug(config, sidebar, currentSlug)
+  if (topicFromSlug) return topicFromSlug
+
+  // Otherwise, find the current topic by looking for the current page in the sidebar.
+  const currentSidebarTopic = getCurrentSidebarTopic(sidebar)
+  if (!currentSidebarTopic) return undefined
+
+  const currentTopicConfig = config[Number.parseInt(currentSidebarTopic.label, 10)]
+  if (!currentTopicConfig) return undefined
+
+  return { config: currentTopicConfig, sidebar: currentSidebarTopic.entries }
+}
+
+export function isTopicFirstPage(sidebar: SidebarEntry[], currentSlug: string): boolean {
+  const currentSidebarTopic = getCurrentSidebarTopic(sidebar)
+  if (!currentSidebarTopic) return false
+
+  const firstPage = getSidebarFirstPage(currentSidebarTopic.entries)
+  if (!firstPage) return false
+
+  return arePathnamesEqual(stripLeadingAndTrailingSlashes(firstPage.href), currentSlug)
+}
+
+export function isTopicLastPage(sidebar: SidebarEntry[], currentSlug: string): boolean {
+  const currentSidebarTopic = getCurrentSidebarTopic(sidebar)
+  if (!currentSidebarTopic) return false
+
+  const lastPage = getSidebarLastPage(currentSidebarTopic.entries)
+  if (!lastPage) return false
+
+  return arePathnamesEqual(stripLeadingAndTrailingSlashes(lastPage.href), currentSlug)
+}
+
+function getSidebarFirstPage(sidebar: SidebarEntry[]) {
+  const entry = sidebar[0]
+  if (!entry) return undefined
+  if (entry.type === "link") return entry
+
+  return getSidebarFirstPage(entry.entries)
+}
+
+function getSidebarLastPage(sidebar: SidebarEntry[]) {
+  const entry = sidebar.at(-1)
+  if (!entry) return undefined
+  if (entry.type === "link") return entry
+
+  return getSidebarLastPage(entry.entries)
+}
+
+function getTopicFromSlug(
+  config: StarlightSidebarTopicsSharedConfig,
+  sidebar: SidebarEntry[],
+  slug: string
+): Topic | undefined {
+  let topicConfig: Topic["config"] | undefined
+  let topicSidebar: Topic["sidebar"] | undefined
+
+  // Start by checking if the current page is a topic homepage.
+  let groupTopicIndex = -1
+  const slugLocale = getLocaleFromSlug(slug)
+
+  for (const topic of config) {
+    if (topic.type === "group") groupTopicIndex++
+
+    if (
+      !absoluteLinkRegex.test(topic.link) &&
+      arePathnamesEqual(
+        getLocalizedSlug(stripLeadingAndTrailingSlashes(topic.link), slugLocale),
+        slug
+      ) &&
+      groupTopicIndex !== -1
+    ) {
+      const sidebarTopic = sidebar[groupTopicIndex]
+
+      if (sidebarTopic?.type === "group") {
+        topicConfig = topic
+        topicSidebar = sidebarTopic.entries
+      }
+
+      break
+    }
+  }
+
+  if (!topicConfig || !topicSidebar) return undefined
+
+  return { config: topicConfig, sidebar: topicSidebar }
+}
+
+export function getTopicById(
+  config: StarlightSidebarTopicsSharedConfig,
+  sidebar: SidebarEntry[],
+  id: string
+): Topic | undefined {
+  let topicConfig: Topic["config"] | undefined
+  let topicSidebar: Topic["sidebar"] | undefined
+
+  let groupTopicIndex = -1
+
+  for (const topic of config) {
+    if (topic.type === "group") groupTopicIndex++
+
+    if (topic.type === "group" && topic.id === id) {
+      const sidebarTopic = sidebar[groupTopicIndex]
+
+      if (sidebarTopic?.type === "group") {
+        topicConfig = topic
+        topicSidebar = sidebarTopic.entries
+      }
+
+      break
+    }
+  }
+
+  if (!topicConfig || !topicSidebar) return undefined
+
+  return { config: topicConfig, sidebar: topicSidebar }
+}
+
+function getCurrentSidebarTopic(sidebar: SidebarEntry[]): SidebarTopic | undefined {
+  let currentSidebarTopic: SidebarTopic | undefined
+
+  for (const topic of sidebar) {
+    if (topic.type === "link") continue
+
+    const currentSidebarEntry = getCurrentSidebarEntry(topic.entries)
+
+    if (currentSidebarEntry) {
+      currentSidebarTopic = topic
+      break
+    }
+  }
+
+  return currentSidebarTopic
+}
+
+function getCurrentSidebarEntry(sidebar: SidebarEntry[]): SidebarEntry | undefined {
+  return sidebar.find((entry) => {
+    if (entry.type === "link") {
+      return entry.isCurrent
+    }
+
+    return getCurrentSidebarEntry(entry.entries)
+  })
+}
+
+function getTopicIdFromEntry(entry: StarlightEntry): string | undefined {
+  if (isStarlightEntryWithTopic(entry)) {
+    return entry.data.topic
+  }
+  return undefined
+}
+
+type SidebarEntry = StarlightRouteData["sidebar"][number]
+
+interface SidebarTopic {
+  label: string
+  entries: SidebarEntry[]
+}
+
+export interface Topic {
+  config: StarlightSidebarTopicsSharedConfig[number]
+  sidebar: SidebarEntry[]
+}

package/src/plugins/starlightAddons/libs/vite.ts

@@ -0,0 +1,46 @@
+import type { ViteUserConfig } from "astro"
+
+import type {
+  StarlightSidebarTopicsConfig,
+  StarlightSidebarTopicsOptions,
+  StarlightSidebarTopicsSharedConfig
+} from "./config"
+
+export function vitePluginStarlightSidebarTopics(
+  config: StarlightSidebarTopicsConfig,
+  options: StarlightSidebarTopicsOptions
+): VitePlugin {
+  const sharedConfig: StarlightSidebarTopicsSharedConfig = config.map((topic) => {
+    if (!("items" in topic)) return { ...topic, type: "link" }
+    // Remove the items property without creating an unused binding
+    const topicWithoutItems: any = { ...topic }
+    delete topicWithoutItems.items
+    return { ...topicWithoutItems, type: "group" }
+  })
+
+  const modules: Record<string, string> = {
+    "virtual:starlight-sidebar-topics/config": `export default ${JSON.stringify(sharedConfig)}`,
+    "virtual:starlight-sidebar-topics/options": `export default ${JSON.stringify(options)}`
+  }
+
+  const moduleResolutionMap = Object.fromEntries(
+    Object.keys(modules).map((key) => [resolveVirtualModuleId(key), key])
+  ) as Record<string, string>
+
+  return {
+    name: "vite-plugin-starlight-sidebar-topics",
+    load(id) {
+      const moduleId = moduleResolutionMap[id]
+      return moduleId ? modules[moduleId] : undefined
+    },
+    resolveId(id) {
+      return id in modules ? resolveVirtualModuleId(id) : undefined
+    }
+  }
+}
+
+function resolveVirtualModuleId<TModuleId extends string>(id: TModuleId): `\0${TModuleId}` {
+  return `\0${id}`
+}
+
+type VitePlugin = NonNullable<ViteUserConfig["plugins"]>[number]

package/src/plugins/starlightAddons/locals.d.ts

@@ -0,0 +1,14 @@
+import type { StarlightLocals } from "@astrojs/starlight/types"
+import type { StarlightSidebarTopicsRouteData } from "./data"
+
+declare namespace App {
+  interface Locals extends StarlightLocals {
+    /**
+     * Starlight Sidebar Topics data.
+     *
+     * @see https://starlight-sidebar-topics.netlify.app/docs/guides/custom-topic-list/
+     */
+    starlightSidebarTopics: StarlightSidebarTopicsRouteData
+    starlightRoute: any
+  }
+}

package/src/plugins/starlightAddons/middleware.ts

@@ -0,0 +1,132 @@
+import { defineRouteMiddleware } from "@astrojs/starlight/route-data"
+import type { APIContext } from "astro"
+import { getRelativeLocaleUrl } from "astro:i18n"
+import picomatch from "picomatch"
+import config from "virtual:starlight-sidebar-topics/config"
+import options from "virtual:starlight-sidebar-topics/options"
+import type { StarlightSidebarTopicsSharedConfig } from "./libs/config"
+import type { StarlightSidebarTopicsSharedOptions } from "./libs/config"
+import type { StarlightEntry } from "./libs/content"
+
+import type { StarlightSidebarTopicsRouteData } from "./data"
+import { getTranslation } from "./libs/i18n"
+import { ensureLeadingSlash } from "./libs/pathname"
+import { throwPluginError } from "./libs/plugin"
+import {
+  getCurrentTopic,
+  getTopicById,
+  isTopicFirstPage,
+  isTopicLastPage,
+  type Topic
+} from "./libs/sidebar"
+
+type StarlightRouteLike = {
+  entry: StarlightEntry
+  hasSidebar: boolean
+  id: string
+  pagination: { prev?: unknown; next?: unknown }
+  sidebar: any[]
+}
+
+export const onRequest = defineRouteMiddleware((context) => {
+  // Locals are augmented to include starlightRoute for typing without casts
+  const { starlightRoute } = context.locals
+  const { entry, hasSidebar, id, pagination, sidebar } = starlightRoute
+
+  const topicsConfig = config as unknown as StarlightSidebarTopicsSharedConfig
+  const topicsOptions = options as unknown as StarlightSidebarTopicsSharedOptions
+
+  let currentTopic: Topic | undefined
+
+  if (hasSidebar) {
+    currentTopic = getCurrentTopic(topicsConfig, sidebar, id, entry)
+
+    if (!currentTopic) {
+      const normalizedId = ensureLeadingSlash(id)
+
+      for (const [topicId, patterns] of Object.entries(topicsOptions.topics)) {
+        if (!picomatch(patterns)(normalizedId)) continue
+        currentTopic = getTopicById(topicsConfig, sidebar, topicId)
+        break
+      }
+    }
+
+    if (!currentTopic) {
+      if (picomatch(options.exclude)(ensureLeadingSlash(id))) {
+        attachRouteData(context, currentTopic)
+        return
+      }
+
+      throwPluginError(
+        `Failed to find the topic for the \`${id}\` page.`,
+        `Either include this page in the sidebar configuration of the desired topic using the \`items\` property, associate an unlisted page with a topic using the \`topic\` frontmatter property or the \`topics\` option, or exclude this page from any topic using the \`exclude\` option.
+
+Learn more in the following guides:
+
+- [Unlisted pages](https://starlight-sidebar-topics.netlify.app/docs/guides/unlisted-pages/)
+- [Excluded pages](https://starlight-sidebar-topics.netlify.app/docs/guides/excluded-pages/)`
+      )
+    }
+
+    starlightRoute.sidebar = currentTopic.sidebar
+
+    if (isTopicFirstPage(sidebar, id)) {
+      pagination.prev = undefined
+    }
+
+    if (isTopicLastPage(sidebar, id)) {
+      pagination.next = undefined
+    }
+  }
+
+  attachRouteData(context, currentTopic)
+})
+
+function attachRouteData(context: APIContext, currentTopic: Topic | undefined) {
+  context.locals.starlightSidebarTopics = getRouteData(context.currentLocale, currentTopic)
+}
+
+function getRouteData(
+  currentLocale: APIContext["currentLocale"],
+  currentTopic: Topic | undefined
+): StarlightSidebarTopicsRouteData {
+  // Build route data with strongly typed config
+  const topicConfigs = config as unknown as StarlightSidebarTopicsSharedConfig
+  return {
+    isPageWithTopic: currentTopic !== undefined,
+    topics: topicConfigs.map((topic) => {
+      const isLinkTopic = topic.type === "link"
+
+      const topicRouteData: StarlightSidebarTopicsRouteData["topics"][number] = {
+        isCurrent:
+          isLinkTopic || !currentTopic
+            ? false
+            : topic.label === currentTopic.config.label && topic.link === currentTopic.config.link,
+        label:
+          typeof topic.label === "string"
+            ? topic.label
+            : getTranslation(currentLocale, topic.label, topic.link, "topic label"),
+        link:
+          !isLinkTopic && currentLocale
+            ? getRelativeLocaleUrl(currentLocale, topic.link)
+            : topic.link
+      }
+
+      if (topic.badge) {
+        topicRouteData.badge = {
+          text:
+            typeof topic.badge.text === "string"
+              ? topic.badge.text
+              : getTranslation(currentLocale, topic.badge.text, topic.link, "topic badge text"),
+          variant: topic.badge.variant
+        }
+      }
+
+      if (topic.icon) {
+        topicRouteData.icon = topic.icon
+      }
+
+      return topicRouteData
+    })
+  }
+}

package/src/plugins/starlightAddons/overrides/Sidebar.astro

@@ -0,0 +1,8 @@
+---
+import Default from '@astrojs/starlight/components/Sidebar.astro'
+
+import StarlightSidebarTopicsSidebar from './Sidebar.astro'
+---
+
+<StarlightSidebarTopicsSidebar />
+<Default><slot /></Default>

package/src/plugins/starlightAddons/schema.ts

@@ -0,0 +1,13 @@
+import { z } from "astro/zod"
+
+export const topicSchema = z.object({
+  /**
+   * ID of the topic to associate with the current page if the page is not listed in any topic
+   * sidebar configuration.
+   *
+   * @see https://starlight-sidebar-topics.netlify.app/docs/guides/unlisted-pages/
+   */
+  topic: z.string().optional()
+})
+
+export type TopicFrontmatterSchema = z.input<typeof topicSchema>

package/src/plugins/starlightAddons/starlight.d.ts

@@ -0,0 +1,6 @@
+declare module "virtual:starlight/user-config" {
+  import type { StarlightConfig } from "@astrojs/starlight/types"
+  const Config: StarlightConfig
+
+  export default Config
+}

package/src/plugins/starlightAddons/virtual.d.ts

@@ -0,0 +1,13 @@
+declare module "virtual:starlight-sidebar-topics/config" {
+  import type { StarlightSidebarTopicsSharedConfig } from "./libs/config"
+  const StarlightSidebarTopicsConfig: StarlightSidebarTopicsSharedConfig
+
+  export default StarlightSidebarTopicsConfig
+}
+
+declare module "virtual:starlight-sidebar-topics/options" {
+  import type { StarlightSidebarTopicsSharedOptions } from "./libs/config"
+  const StarlightSidebarTopicsOptions: StarlightSidebarTopicsSharedOptions
+
+  export default StarlightSidebarTopicsOptions
+}

package/src/middleware/sri.ts

@@ -1,78 +0,0 @@
-import { defineMiddleware } from "astro:middleware"
-// @ts-ignore - virtual module generated by the SRI integration
-import { manifest } from "virtual:sri-manifest"
-
-declare const HTMLRewriter: any
-
-function assertManifest(obj: unknown): asserts obj is Record<string, string> {
-  if (!obj || typeof obj !== "object") throw new Error("Expected manifest")
-}
-
-/**
- * SRI Middleware Injects integrity attributes into script tags based on the pre-generated manifest.
- * Handles both SSR streaming (via HTMLRewriter) and post-rendering fallback.
- */
-export const sri = defineMiddleware(async (_, next) => {
-  const response = await next()
-  const contentType = response.headers.get("content-type") || ""
-
-  // Only process HTML responses
-  if (!contentType.includes("text/html")) {
-    return response
-  }
-
-  // Use Cloudflare's HTMLRewriter if available (SSR Production/Preview)
-  if (typeof HTMLRewriter !== "undefined") {
-    return new HTMLRewriter()
-      .on("script[src]", {
-        element(el: any) {
-          const src = el.getAttribute("src")
-          if (src && manifest[src]) {
-            el.setAttribute("integrity", manifest[src])
-            el.setAttribute("crossorigin", "anonymous")
-          }
-        }
-      })
-      .on('link[rel="stylesheet"][href]', {
-        element(el: any) {
-          const href = el.getAttribute("href")
-          if (href && manifest[href]) {
-            el.setAttribute("integrity", manifest[href])
-            el.setAttribute("crossorigin", "anonymous")
-          }
-        }
-      })
-      .transform(response)
-  }
-
-  // Fallback for Dev
-  let modifiedHtml = await response.text()
-
-  // Simple RegEx replacement for Dev inspection
-  assertManifest(manifest)
-
-  const entries = Object.entries(manifest)
-  for (const [url, hash] of entries) {
-    if (!hash) continue
-
-    // Look for script tags with the specific URL
-    const scriptRegex = new RegExp(`(<script[^>]+src=["']${url}["'][^>]*)(/?>)`, "g")
-    modifiedHtml = modifiedHtml.replace(
-      scriptRegex,
-      `$1 integrity="${hash}" crossorigin="anonymous"$2`
-    )
-
-    // Look for link tags with the specific URL
-    const linkRegex = new RegExp(`(<link[^>]+href=["']${url}["'][^>]*)(/?>)`, "g")
-    modifiedHtml = modifiedHtml.replace(
-      linkRegex,
-      `$1 integrity="${hash}" crossorigin="anonymous"$2`
-    )
-  }
-
-  return new Response(modifiedHtml, {
-    status: response.status,
-    statusText: response.statusText,
-    headers: response.headers
-  })
-})