@ciderpress/ui 1.0.0-rc.1

package/dist/theme/icons/tech-map.ts

@@ -0,0 +1,228 @@
+/**
+ * Predefined technology tag to Iconify identifier + display label.
+ *
+ * Uses `devicon` as the primary source for colored icons, with `logos`,
+ * `vscode-icons`, and `material-icon-theme` filling gaps. A small number
+ * of entries fall back to `simple-icons` (monochrome) when no colored
+ * alternative exists.
+ *
+ * Add new entries here when new technologies need card support.
+ *
+ * @example
+ * ```ts
+ * const { icon, label } = TECH_ICONS['typescript']
+ * ```
+ */
+export const TECH_ICONS = {
+  // -- Languages --
+  typescript: { icon: 'devicon:typescript', label: 'TypeScript' },
+  javascript: { icon: 'devicon:javascript', label: 'JavaScript' },
+  python: { icon: 'devicon:python', label: 'Python' },
+  go: { icon: 'devicon:go', label: 'Go' },
+  rust: { icon: 'devicon:rust', label: 'Rust' },
+  java: { icon: 'devicon:java', label: 'Java' },
+  csharp: { icon: 'devicon:csharp', label: 'C#' },
+  ruby: { icon: 'devicon:ruby', label: 'Ruby' },
+  php: { icon: 'devicon:php', label: 'PHP' },
+  swift: { icon: 'devicon:swift', label: 'Swift' },
+  kotlin: { icon: 'devicon:kotlin', label: 'Kotlin' },
+  elixir: { icon: 'devicon:elixir', label: 'Elixir' },
+  dart: { icon: 'devicon:dart', label: 'Dart' },
+  scala: { icon: 'devicon:scala', label: 'Scala' },
+  c: { icon: 'devicon:c', label: 'C' },
+  cplusplus: { icon: 'devicon:cplusplus', label: 'C++' },
+  r: { icon: 'devicon:r', label: 'R' },
+  lua: { icon: 'devicon:lua', label: 'Lua' },
+  perl: { icon: 'devicon:perl', label: 'Perl' },
+  haskell: { icon: 'devicon:haskell', label: 'Haskell' },
+  clojure: { icon: 'devicon:clojure', label: 'Clojure' },
+  erlang: { icon: 'devicon:erlang', label: 'Erlang' },
+  fsharp: { icon: 'devicon:fsharp', label: 'F#' },
+  julia: { icon: 'devicon:julia', label: 'Julia' },
+  groovy: { icon: 'devicon:groovy', label: 'Groovy' },
+
+  // -- Frontend frameworks --
+  react: { icon: 'devicon:react', label: 'React' },
+  nextjs: { icon: 'devicon:nextjs', label: 'Next.js' },
+  vue: { icon: 'devicon:vuejs', label: 'Vue' },
+  angular: { icon: 'devicon:angular', label: 'Angular' },
+  svelte: { icon: 'devicon:svelte', label: 'Svelte' },
+  astro: { icon: 'devicon:astro', label: 'Astro' },
+  solid: { icon: 'devicon:solidjs', label: 'Solid' },
+  remix: { icon: 'devicon:remix', label: 'Remix' },
+  qwik: { icon: 'devicon:qwik', label: 'Qwik' },
+  ember: { icon: 'devicon:ember', label: 'Ember' },
+  gatsby: { icon: 'devicon:gatsby', label: 'Gatsby' },
+  nuxtjs: { icon: 'devicon:nuxtjs', label: 'Nuxt' },
+  preact: { icon: 'logos:preact', label: 'Preact' },
+  lit: { icon: 'logos:lit', label: 'Lit' },
+
+  // -- Backend frameworks --
+  hono: { icon: 'logos:hono', label: 'Hono' },
+  express: { icon: 'devicon:express', label: 'Express' },
+  fastify: { icon: 'devicon:fastify', label: 'Fastify' },
+  nestjs: { icon: 'devicon:nestjs', label: 'NestJS' },
+  django: { icon: 'logos:django-icon', label: 'Django' },
+  flask: { icon: 'devicon:flask', label: 'Flask' },
+  rails: { icon: 'devicon:rails-wordmark', label: 'Rails' },
+  spring: { icon: 'devicon:spring', label: 'Spring' },
+  fastapi: { icon: 'devicon:fastapi', label: 'FastAPI' },
+  laravel: { icon: 'devicon:laravel', label: 'Laravel' },
+  phoenix: { icon: 'devicon:phoenix', label: 'Phoenix' },
+  fiber: { icon: 'devicon:fiber', label: 'Fiber' },
+  gin: { icon: 'logos:gin', label: 'Gin' },
+  akka: { icon: 'devicon:akka', label: 'Akka' },
+
+  // -- Mobile --
+  flutter: { icon: 'devicon:flutter', label: 'Flutter' },
+  reactnative: { icon: 'devicon:reactnative', label: 'React Native' },
+  ionic: { icon: 'devicon:ionic', label: 'Ionic' },
+
+  // -- Databases --
+  postgresql: { icon: 'devicon:postgresql', label: 'PostgreSQL' },
+  mysql: { icon: 'devicon:mysql', label: 'MySQL' },
+  mongodb: { icon: 'devicon:mongodb', label: 'MongoDB' },
+  redis: { icon: 'devicon:redis', label: 'Redis' },
+  sqlite: { icon: 'devicon:sqlite', label: 'SQLite' },
+  dynamodb: { icon: 'devicon:dynamodb', label: 'DynamoDB' },
+  elasticsearch: { icon: 'devicon:elasticsearch', label: 'Elasticsearch' },
+  neo4j: { icon: 'devicon:neo4j', label: 'Neo4j' },
+  cassandra: { icon: 'devicon:cassandra', label: 'Cassandra' },
+  couchdb: { icon: 'devicon:couchdb', label: 'CouchDB' },
+  mariadb: { icon: 'devicon:mariadb', label: 'MariaDB' },
+  influxdb: { icon: 'devicon:influxdb', label: 'InfluxDB' },
+  cockroachdb: { icon: 'simple-icons:cockroachlabs', label: 'CockroachDB' },
+  vitess: { icon: 'devicon:vitess', label: 'Vitess' },
+  oracle: { icon: 'devicon:oracle', label: 'Oracle' },
+
+  // -- ORM / Data tools --
+  prisma: { icon: 'devicon:prisma', label: 'Prisma' },
+  graphql: { icon: 'logos:graphql', label: 'GraphQL' },
+  drizzle: { icon: 'logos:drizzle', label: 'Drizzle' },
+  typeorm: { icon: 'logos:typeorm', label: 'TypeORM' },
+  sequelize: { icon: 'logos:sequelize', label: 'Sequelize' },
+  sqlalchemy: { icon: 'devicon:sqlalchemy', label: 'SQLAlchemy' },
+
+  // -- Cloud & hosting --
+  vercel: { icon: 'devicon:vercel', label: 'Vercel' },
+  aws: { icon: 'devicon:amazonwebservices', label: 'AWS' },
+  azure: { icon: 'devicon:azure', label: 'Azure' },
+  gcp: { icon: 'devicon:googlecloud', label: 'GCP' },
+  cloudflare: { icon: 'devicon:cloudflare', label: 'Cloudflare' },
+  digitalocean: { icon: 'devicon:digitalocean', label: 'DigitalOcean' },
+  heroku: { icon: 'devicon:heroku', label: 'Heroku' },
+  netlify: { icon: 'devicon:netlify', label: 'Netlify' },
+  firebase: { icon: 'devicon:firebase', label: 'Firebase' },
+  supabase: { icon: 'devicon:supabase', label: 'Supabase' },
+  railway: { icon: 'devicon:railway', label: 'Railway' },
+  pulumi: { icon: 'devicon:pulumi', label: 'Pulumi' },
+  fly: { icon: 'logos:fly-icon', label: 'Fly.io' },
+
+  // -- CI/CD & DevOps --
+  docker: { icon: 'devicon:docker', label: 'Docker' },
+  kubernetes: { icon: 'devicon:kubernetes', label: 'Kubernetes' },
+  github: { icon: 'devicon:github', label: 'GitHub' },
+  'github-actions': { icon: 'devicon:githubactions', label: 'GitHub Actions' },
+  gitlab: { icon: 'devicon:gitlab', label: 'GitLab' },
+  circleci: { icon: 'logos:circleci', label: 'CircleCI' },
+  terraform: { icon: 'devicon:terraform', label: 'Terraform' },
+  ansible: { icon: 'devicon:ansible', label: 'Ansible' },
+  jenkins: { icon: 'devicon:jenkins', label: 'Jenkins' },
+  argocd: { icon: 'devicon:argocd', label: 'Argo CD' },
+
+  // -- Build & package tools --
+  vite: { icon: 'devicon:vite', label: 'Vite' },
+  webpack: { icon: 'devicon:webpack', label: 'Webpack' },
+  npm: { icon: 'devicon:npm', label: 'npm' },
+  pnpm: { icon: 'devicon:pnpm', label: 'pnpm' },
+  yarn: { icon: 'devicon:yarn', label: 'Yarn' },
+  bun: { icon: 'devicon:bun', label: 'Bun' },
+  eslint: { icon: 'devicon:eslint', label: 'ESLint' },
+  babel: { icon: 'devicon:babel', label: 'Babel' },
+  turborepo: { icon: 'logos:turborepo-icon', label: 'Turborepo' },
+  biome: { icon: 'devicon:biome', label: 'Biome' },
+  prettier: { icon: 'logos:prettier', label: 'Prettier' },
+  esbuild: { icon: 'logos:esbuild', label: 'esbuild' },
+  rollup: { icon: 'devicon:rollup', label: 'Rollup' },
+  swc: { icon: 'logos:swc', label: 'SWC' },
+  gradle: { icon: 'devicon:gradle', label: 'Gradle' },
+  maven: { icon: 'devicon:maven', label: 'Maven' },
+
+  // -- UI & styling --
+  tailwindcss: { icon: 'devicon:tailwindcss', label: 'Tailwind CSS' },
+  css: { icon: 'devicon:css3', label: 'CSS' },
+  html: { icon: 'devicon:html5', label: 'HTML' },
+  sass: { icon: 'devicon:sass', label: 'Sass' },
+  bootstrap: { icon: 'devicon:bootstrap', label: 'Bootstrap' },
+  materialui: { icon: 'devicon:materialui', label: 'Material UI' },
+  'shadcn-ui': { icon: 'vscode-icons:file-type-shadcn', label: 'shadcn/ui' },
+  storybook: { icon: 'devicon:storybook', label: 'Storybook' },
+  figma: { icon: 'devicon:figma', label: 'Figma' },
+
+  // -- Testing --
+  jest: { icon: 'logos:jest', label: 'Jest' },
+  vitest: { icon: 'devicon:vitest', label: 'Vitest' },
+  cypress: { icon: 'devicon:cypressio', label: 'Cypress' },
+  playwright: { icon: 'devicon:playwright', label: 'Playwright' },
+  selenium: { icon: 'devicon:selenium', label: 'Selenium' },
+  mocha: { icon: 'devicon:mocha', label: 'Mocha' },
+  puppeteer: { icon: 'devicon:puppeteer', label: 'Puppeteer' },
+  cucumber: { icon: 'logos:cucumber', label: 'Cucumber' },
+
+  // -- Auth & integrations --
+  oauth: { icon: 'devicon:oauth', label: 'OAuth' },
+  auth0: { icon: 'logos:auth0', label: 'Auth0' },
+  stripe: { icon: 'logos:stripe', label: 'Stripe' },
+  twilio: { icon: 'devicon:twilio', label: 'Twilio' },
+
+  // -- AI / ML --
+  openai: { icon: 'logos:openai-icon', label: 'OpenAI' },
+  tensorflow: { icon: 'devicon:tensorflow', label: 'TensorFlow' },
+  pytorch: { icon: 'devicon:pytorch', label: 'PyTorch' },
+  huggingface: { icon: 'devicon:huggingface', label: 'Hugging Face' },
+  anthropic: { icon: 'logos:anthropic-icon', label: 'Anthropic' },
+  jupyter: { icon: 'devicon:jupyter', label: 'Jupyter' },
+  numpy: { icon: 'devicon:numpy', label: 'NumPy' },
+  pandas: { icon: 'devicon:pandas', label: 'Pandas' },
+  scikitlearn: { icon: 'devicon:scikitlearn', label: 'scikit-learn' },
+  matplotlib: { icon: 'devicon:matplotlib', label: 'Matplotlib' },
+
+  // -- Monitoring & observability --
+  grafana: { icon: 'devicon:grafana', label: 'Grafana' },
+  prometheus: { icon: 'devicon:prometheus', label: 'Prometheus' },
+  datadog: { icon: 'devicon:datadog', label: 'Datadog' },
+  sentry: { icon: 'devicon:sentry', label: 'Sentry' },
+  newrelic: { icon: 'devicon:newrelic', label: 'New Relic' },
+
+  // -- Message queues --
+  kafka: { icon: 'devicon:apachekafka', label: 'Kafka' },
+  rabbitmq: { icon: 'devicon:rabbitmq', label: 'RabbitMQ' },
+  nats: { icon: 'devicon:nats', label: 'NATS' },
+
+  // -- CMS --
+  strapi: { icon: 'logos:strapi', label: 'Strapi' },
+  contentful: { icon: 'logos:contentful', label: 'Contentful' },
+  sanity: { icon: 'devicon:sanity', label: 'Sanity' },
+  wordpress: { icon: 'devicon:wordpress', label: 'WordPress' },
+  shopify: { icon: 'logos:shopify', label: 'Shopify' },
+  ghost: { icon: 'devicon:ghost', label: 'Ghost' },
+
+  // -- Infrastructure --
+  node: { icon: 'devicon:nodejs', label: 'Node.js' },
+
+  nginx: { icon: 'devicon:nginx', label: 'Nginx' },
+  apache: { icon: 'devicon:apache', label: 'Apache' },
+  linux: { icon: 'devicon:linux', label: 'Linux' },
+
+  // -- Project-specific (label-only fallback when icon not in any set) --
+  'trigger-dev': { icon: 'material-icon-theme:trigger', label: 'Trigger.dev' },
+  'ai-sdk': { icon: 'simple-icons:vercel', label: 'AI SDK' },
+  openrouter: { icon: 'simple-icons:openrouter', label: 'OpenRouter' },
+  liquid: { icon: 'vscode-icons:file-type-liquid', label: 'Liquid' },
+  zod: { icon: 'logos:zod', label: 'Zod' },
+} as const satisfies Record<string, { readonly icon: string; readonly label: string }>
+
+/**
+ * Union of all supported technology tag names.
+ */
+export type TechName = keyof typeof TECH_ICONS

package/dist/theme/index.tsx

@@ -0,0 +1,180 @@
+/**
+ * ciderpress Rspress theme entry.
+ *
+ * Re-exports the default Rspress theme and extends it with
+ * ciderpress-specific components.
+ *
+ * Global styles are imported here so Rspress includes them
+ * in the site bundle when this theme entry is loaded.
+ */
+
+// Rspress sibling CSS for components we shadow below. Re-exporting a ciderpress
+// component under the same name (e.g. `CiderpressDocLayout as DocLayout`) lets the
+// bundler tree-shake the original Rspress module — and with it the sibling
+// `./index.css` side-effect import that ships the base structural styles. Import
+// each sibling CSS file directly here so it survives the override.
+import '@rspress/core/dist/theme/layout/DocLayout/index.css'
+import '@rspress/core/dist/theme/components/HomeFeature/index.css'
+import '@rspress/core/dist/theme/components/Sidebar/SidebarDivider.css'
+import '@rspress/core/dist/theme/components/Sidebar/SidebarGroup.css'
+import '@rspress/core/dist/theme/components/Sidebar/SidebarItem.css'
+import '@rspress/core/dist/theme/components/Sidebar/SidebarSectionHeader.css'
+
+import './styles/layers.css'
+import './styles/overrides/fonts.css'
+import './styles/overrides/tokens.css'
+import './styles/overrides/rspress.css'
+// Theme color palettes — scoped via [data-cp-theme][data-cp-variant] selectors.
+// `mulled.css` ships first because it is `DEFAULT_THEME_NAME` — its rules emit
+// the `:root { ... }` FOUC fallback that paints before JS hydrates the
+// `data-cp-theme` attribute on `<html>`.
+import './styles/themes/mulled.css'
+import './styles/themes/honeycrisp.css'
+import './styles/themes/grannysmith.css'
+import './styles/themes/amber.css'
+import './styles/themes/midnight.css'
+import './styles/themes/arcade.css'
+// arcade-fx.css is intentionally separate from arcade.css:
+// arcade.css = color palette tokens, arcade-fx.css = visual effects
+// (border trace, neon pulse, CRT scanlines, etc.) scoped to [data-cp-theme='arcade']
+import './styles/themes/arcade-fx.css'
+import './styles/overrides/details.css'
+import './styles/overrides/scrollbar.css'
+import './styles/overrides/rail.css'
+import './styles/overrides/sidebar.css'
+import './styles/overrides/content-footer.css'
+import './styles/overrides/home.css'
+import './styles/overrides/home-card.css'
+import './styles/overrides/section-card.css'
+import './styles/overrides/vscode.css'
+import './styles/overrides/badge.css'
+import './components/announcement/announcement-bar.css'
+import './components/ask-ai/ask-ai-button.css'
+import './components/content-footer/feedback.css'
+import './components/content-footer/meta-actions.css'
+import './components/content-footer/page-pager.css'
+import './components/sidebar/framework-picker.css'
+import './components/sidebar/sidebar-promo.css'
+import './components/sidebar/sidebar-toggle.css'
+import './components/home/page-rail.css'
+import './components/home/hero.css'
+import './components/home/hero-demo.css'
+import './components/home/trust-strip.css'
+import './components/home/split.css'
+import './components/home/cta.css'
+import './components/nav/ciderpress-docs-bar.css'
+import './components/nav/nav-logo.css'
+import './components/nav/version-chip.css'
+import './components/nav/topbar-cta.css'
+import './components/openapi/openapi.css'
+import './components/shared/accordion.css'
+import './components/shared/columns.css'
+import './components/shared/status-badge.css'
+import './components/shared/frame.css'
+import './components/shared/tooltip.css'
+import './components/shared/prompt.css'
+import './components/shared/color.css'
+import './components/shared/theme-color-palette.css'
+import './components/shared/steps.css'
+import './components/shared/field.css'
+
+export * from '@rspress/core/theme-original'
+
+/** @internal Rspress layout override — injects ciderpress nav components via layout slots */
+export { Layout } from './components/nav/layout'
+/** @internal Rspress doc-layout override — replaces `.rp-doc-layout__menu` with `<CiderpressDocsBar />` */
+export { CiderpressDocLayout as DocLayout } from './components/nav/ciderpress-doc-layout'
+/** @internal Home page feature block override */
+export { HomeFeature } from './components/home/feature'
+/** @internal Home page layout override */
+export { HomeLayout } from './components/home/layout'
+/** @internal Sidebar override — multi-scope filtering for standalone sections */
+export { Sidebar } from './components/sidebar/sidebar-scope'
+
+export { FeatureCard, FeatureGrid } from './components/home/feature-card'
+export type { FeatureCardProps, FeatureItem } from './components/home/feature-card'
+export { PageRail } from './components/home/page-rail'
+export type { PageRailProps } from './components/home/page-rail'
+export { Hero } from './components/home/hero'
+export type { HeroProps, HeroAction } from './components/home/hero'
+export { HeroDemo } from './components/home/hero-demo'
+export { TrustStrip } from './components/home/trust-strip'
+export type { TrustStripProps } from './components/home/trust-strip'
+export { HomeSplit } from './components/home/split'
+export type { SplitProps, SplitAction } from './components/home/split'
+export { CTA } from './components/home/cta'
+export type { CTAProps } from './components/home/cta'
+export { WorkspaceCard } from './components/workspaces/card'
+export type { WorkspaceCardProps } from './components/workspaces/card'
+export { WorkspaceGrid } from './components/workspaces/grid'
+export type { WorkspaceGridProps } from './components/workspaces/grid'
+export { SectionCard } from './components/shared/section-card'
+export type { SectionCardProps } from './components/shared/section-card'
+export { SectionGrid } from './components/shared/section-grid'
+export type { SectionGridProps } from './components/shared/section-grid'
+
+export { DesktopWindow } from './components/shared/desktop-window'
+export type { DesktopWindowProps, WindowTab } from './components/shared/desktop-window'
+export { BrowserWindow } from './components/shared/desktop-window'
+export type { BrowserWindowProps, BrowserTab } from './components/shared/desktop-window'
+export { IDEWindow } from './components/shared/desktop-window'
+export type { IDEWindowProps, IDEFileTab } from './components/shared/desktop-window'
+export { TerminalWindow, Command, Output, Line } from './components/shared/desktop-window'
+export type {
+  TerminalWindowProps,
+  TerminalColor,
+  TerminalLineConfig,
+  CommandProps,
+  OutputProps,
+  LineProps,
+} from './components/shared/desktop-window'
+
+export { Accordion, AccordionGroup } from './components/shared/accordion'
+export type { AccordionProps, AccordionGroupProps } from './components/shared/accordion'
+export { Columns, Column } from './components/shared/columns'
+export type { ColumnsProps, ColumnProps } from './components/shared/columns'
+export { Badge } from './components/shared/status-badge'
+export type { BadgeProps, BadgeVariant } from './components/shared/status-badge'
+export { Frame } from './components/shared/frame'
+export type { FrameProps } from './components/shared/frame'
+export { Tooltip } from './components/shared/tooltip'
+export type { TooltipProps } from './components/shared/tooltip'
+export { Prompt } from './components/shared/prompt'
+export type { PromptProps, PromptAction } from './components/shared/prompt'
+export { Color } from './components/shared/color'
+export type { ColorProps } from './components/shared/color'
+export { ThemeColorPalette } from './components/shared/theme-color-palette'
+export type { ThemeColorPaletteProps } from './components/shared/theme-color-palette'
+export { Steps, Step } from './components/shared/steps'
+export type { StepsProps, StepProps } from './components/shared/steps'
+export { Field, FieldGroup } from './components/shared/field'
+export type { FieldProps, FieldGroupProps } from './components/shared/field'
+
+export { CopyMarkdownButton } from './components/openapi'
+export type { CopyMarkdownButtonProps } from './components/openapi'
+export { OpenAPIOperation } from './components/openapi'
+export type { OpenAPIOperationProps } from './components/openapi'
+export { OpenAPIOverview } from './components/openapi'
+export type { OpenAPIOverviewProps } from './components/openapi'
+
+export { AnnouncementBar } from './components/announcement/announcement-bar'
+export type { AnnouncementBarProps } from './components/announcement/announcement-bar'
+export { AskAIButton } from './components/ask-ai/ask-ai-button'
+export type { AskAIButtonProps } from './components/ask-ai/ask-ai-button'
+export { Feedback } from './components/content-footer/feedback'
+export type { FeedbackProps } from './components/content-footer/feedback'
+export { MetaActions } from './components/content-footer/meta-actions'
+export type { MetaAction, MetaActionsProps } from './components/content-footer/meta-actions'
+export { PagePager } from './components/content-footer/page-pager'
+export type { PagePagerProps, PagerLink } from './components/content-footer/page-pager'
+export { FrameworkPicker } from './components/sidebar/framework-picker'
+export type { FrameworkPickerProps } from './components/sidebar/framework-picker'
+export { SidebarPromo } from './components/sidebar/sidebar-promo'
+export type { SidebarPromoProps } from './components/sidebar/sidebar-promo'
+export { SidebarToggle } from './components/sidebar/sidebar-toggle'
+
+export { Icon } from './components/shared/icon'
+export { TechTag } from './components/shared/tech-tag'
+export type { TechTagProps } from './components/shared/tech-tag'
+export { TechIconTable } from './components/shared/tech-icon-table'
+export type { TechIconEntry, TechIconTableProps } from './components/shared/tech-icon-table'

package/dist/theme/lib/read-social-links.ts

@@ -0,0 +1,27 @@
+import type { CiderpressSocialLink } from '../components/nav/ciderpress-nav-social-links'
+
+/**
+ * Pull social-link entries (GitHub, npm, etc) from Rspress's `site`
+ * shape. Lives on `site.themeConfig.socialLinks` after Rspress
+ * normalisation but isn't surfaced on the public typings.
+ *
+ * @param site - Rspress site data (typically the result of `useSite().site`)
+ * @returns Array of social-link entries (empty array when not configured)
+ */
+export function readSocialLinks(site: unknown): readonly CiderpressSocialLink[] {
+  const { themeConfig } = site as { readonly themeConfig?: unknown }
+  if (themeConfig === undefined || themeConfig === null) {
+    return []
+  }
+  const candidate = (themeConfig as { readonly socialLinks?: unknown }).socialLinks
+  if (!Array.isArray(candidate)) {
+    return []
+  }
+  return candidate.filter(
+    (item): item is CiderpressSocialLink =>
+      typeof item === 'object' &&
+      item !== null &&
+      typeof (item as { icon?: unknown }).icon === 'string' &&
+      typeof (item as { content?: unknown }).content === 'string'
+  )
+}

package/dist/theme/lib/route-link.tsx

@@ -0,0 +1,126 @@
+import { Link } from '@rspress/core/runtime'
+import type React from 'react'
+
+/**
+ * Props accepted by the {@link RouteLink} helper. Mirror `<a>` props but
+ * narrow `href` to a required string (we route on it).
+ */
+export interface RouteLinkProps {
+  /**
+   * Destination URL. Internal paths (anything starting with `/` or `#`)
+   * are routed through Rspress's `<Link>` so navigation stays SPA
+   * (no full document load). Everything else is treated as external and
+   * rendered as a plain anchor.
+   */
+  readonly href: string
+  /**
+   * Optional class applied to the rendered element.
+   */
+  readonly className?: string
+  /**
+   * Optional inline ARIA label.
+   */
+  readonly 'aria-label'?: string
+  /**
+   * Optional ARIA current marker (e.g. `'page'`).
+   */
+  readonly 'aria-current'?: React.AriaAttributes['aria-current']
+  /**
+   * Optional `role` attribute (e.g. `'menuitem'`).
+   */
+  readonly role?: string
+  /**
+   * Optional title attribute.
+   */
+  readonly title?: string
+  /**
+   * Optional click handler (closing dropdowns, etc.).
+   */
+  readonly onClick?: React.MouseEventHandler<HTMLElement>
+  /**
+   * Optional data-* attribute used by the nav menu measure layer.
+   */
+  readonly 'data-cp-menu-item'?: boolean | string
+  /**
+   * Rendered children.
+   */
+  readonly children: React.ReactNode
+}
+
+/**
+ * Render an in-app link that prefers SPA navigation when the destination
+ * is internal, falling back to a plain `<a>` for external URLs.
+ *
+ * Internal hrefs (starting with `/` or `#`) go through Rspress's
+ * `Link` from `@rspress/core/runtime` — that's a thin wrapper over
+ * `react-router-dom`'s `Link`, so the click is intercepted and routed
+ * through history without a full page reload.
+ *
+ * External hrefs (`http://`, `https://`, `mailto:`, `tel:`, `data:`,
+ * etc.) render as `<a target="_blank" rel="noopener noreferrer">` so
+ * clicks open in a new tab and the document doesn't leak `window.opener`.
+ *
+ * @param props - Link props (href + presentational/ARIA attributes)
+ * @returns React element (`<Link>` for internal, `<a>` for external)
+ */
+export function RouteLink(props: RouteLinkProps): React.ReactElement {
+  const isInternal = isInternalHref(props.href)
+  if (isInternal) {
+    return (
+      <Link
+        to={props.href}
+        className={props.className}
+        aria-label={props['aria-label']}
+        aria-current={props['aria-current']}
+        role={props.role}
+        title={props.title}
+        onClick={props.onClick}
+        data-cp-menu-item={props['data-cp-menu-item']}
+      >
+        {props.children}
+      </Link>
+    )
+  }
+  return (
+    <a
+      href={props.href}
+      className={props.className}
+      aria-label={props['aria-label']}
+      aria-current={props['aria-current']}
+      role={props.role}
+      title={props.title}
+      onClick={props.onClick}
+      data-cp-menu-item={props['data-cp-menu-item']}
+      target="_blank"
+      rel="noopener noreferrer"
+    >
+      {props.children}
+    </a>
+  )
+}
+
+/**
+ * Decide whether `href` points at an in-app route. Internal URLs are
+ * absolute paths (`/foo`) or anchors (`#bar`). Everything else — full
+ * URLs with a scheme, scheme-relative URLs, mailto, tel, etc. — is
+ * treated as external.
+ *
+ * @private
+ * @param href - Candidate destination
+ * @returns `true` when `href` should be SPA-routed
+ */
+function isInternalHref(href: string): boolean {
+  if (href.length === 0) {
+    return false
+  }
+  if (href.startsWith('//')) {
+    return false
+  }
+  if (href.startsWith('/')) {
+    return true
+  }
+  if (href.startsWith('#')) {
+    return true
+  }
+  return false
+}

package/dist/theme/lib/safe-url.ts

@@ -0,0 +1,68 @@
+import { match, P } from 'massaman/match'
+
+const SAFE_PROTOCOLS: ReadonlySet<string> = new Set(['http:', 'https:', 'mailto:', 'tel:'])
+
+const PROTOCOL_PATTERN = /^[a-z][a-z0-9+.-]*:/i
+
+// ASCII whitespace + control characters that browsers strip when
+// normalising URL schemes — U+0000–U+0020 (NUL through SPACE) plus
+// U+007F (DEL). A href like `java\nscript:alert(1)` or `java script:`
+// looks "relative" to a naive scheme regex but resolves to
+// `javascript:` once a browser parses it for navigation. We reject any
+// such character anywhere in the input as the cheap fix.
+// oxlint-disable-next-line no-control-regex -- matching control chars is the point
+const FORBIDDEN_CHARS_PATTERN = /[\u0000-\u0020\u007F]/u
+
+/**
+ * Return `href` when it points at a safe location, otherwise `null`.
+ *
+ * Safe locations: relative paths, fragment anchors (`#section`),
+ * absolute http/https URLs, `mailto:`, and `tel:`. Any other scheme —
+ * including `javascript:`, `data:`, `vbscript:`, `file:` — returns `null`
+ * so the caller can either omit the link or fall back to a placeholder.
+ *
+ * Inputs containing ASCII whitespace or control characters (newline, tab,
+ * carriage return, space) anywhere are rejected outright — browsers strip
+ * those during URL normalisation, so a value like `"java\nscript:alert(1)"`
+ * resolves to `javascript:` post-parse even though the scheme regex won't
+ * catch it. This is the documented bypass for naïve allow-lists.
+ *
+ * Validation is whitespace-trimmed and scheme detection is case-insensitive
+ * so `JaVaScRiPt:` is rejected the same way `javascript:` is.
+ *
+ * @param href - The URL string to validate.
+ * @returns The trimmed `href` when safe, or `null` when the scheme is not allowed.
+ *
+ * @example
+ * safeUrl('/docs/intro')            // → '/docs/intro'
+ * safeUrl('https://example.com')    // → 'https://example.com'
+ * safeUrl('javascript:alert(1)')    // → null
+ * safeUrl('java\nscript:alert(1)')  // → null  (control-char smuggling)
+ * safeUrl('java script:alert(1)')   // → null  (whitespace smuggling)
+ */
+export function safeUrl(href: string): string | null {
+  // Trim outer whitespace first so `'  /docs  '` survives, but any
+  // whitespace or control character INSIDE the value is treated as
+  // scheme-smuggling and rejected.
+  const trimmed = href.trim()
+  if (FORBIDDEN_CHARS_PATTERN.test(trimmed)) {
+    return null
+  }
+  return match(trimmed)
+    .with('', () => null)
+    .with(P.string.startsWith('#'), () => trimmed)
+    .with(P.string.startsWith('/'), () => trimmed)
+    .with(P.string.startsWith('./'), () => trimmed)
+    .with(P.string.startsWith('../'), () => trimmed)
+    .otherwise(() => {
+      const match_ = trimmed.match(PROTOCOL_PATTERN)
+      if (!match_) {
+        return trimmed
+      }
+      const scheme = match_[0].toLowerCase()
+      if (SAFE_PROTOCOLS.has(scheme)) {
+        return trimmed
+      }
+      return null
+    })
+}