@rimelight/ui 0.0.1

package/src/domain/i18n/format.ts

@@ -0,0 +1,90 @@
+// Sanitizer: Turns <script> into &lt;script&gt;
+function escapeHtml(unsafe: string | number): string {
+  return String(unsafe)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;")
+}
+
+type TemplateValues = Record<string, string | number>
+
+/**
+ * Interpolates {placeholders} in a template string and escapes values. - If `template` is
+ * undefined/null, returns an empty string (and logs in dev). - If `values` is undefined, returns
+ * the template unchanged.
+ */
+export function fmt(template: string | null | undefined, values?: TemplateValues): string {
+  if (template == null) {
+    if (!import.meta.env.PROD) {
+      console.warn("[i18n] fmt() called with null/undefined template")
+    }
+    return ""
+  }
+
+  if (!values) return template
+
+  return template.replace(/\{([^}]+)\}/g, (match, key) => {
+    const replacement = values[key]
+
+    if (replacement === undefined || replacement === null) {
+      return match
+    }
+
+    return escapeHtml(replacement)
+  })
+}
+
+/**
+ * Simple two-form plural helper. Good for English-like languages where "1" vs "other" is enough.
+ */
+export function plural(count: number, singular: string, pluralForm: string): string {
+  return count === 1 ? singular : fmt(pluralForm, { count })
+}
+
+/**
+ * ICU-style plural categories used by Intl.PluralRules.
+ */
+export type PluralCategory = "zero" | "one" | "two" | "few" | "many" | "other"
+
+export type PluralPatterns = Partial<Record<PluralCategory, string>>
+
+/**
+ * Advanced plural helper using Intl.PluralRules + fmt().
+ *
+ * - `locale` controls plural categories (en, de, es, ja, ...).
+ * - `patterns` comes from KV (e.g. { zero, one, other }).
+ * - Missing categories fall back to `other`.
+ *
+ * Example: pluralIcu(5, 'en', { zero: 'No items', one: '{count} item', other: '{count} items' })
+ */
+export function pluralIcu(count: number, locale: string, patterns: PluralPatterns): string {
+  const rules = new Intl.PluralRules(locale)
+  const cat = rules.select(count) as PluralCategory
+
+  const template =
+    patterns[cat] ??
+    patterns.other ??
+    (import.meta.env.PROD ? "" : (console.warn('[i18n] pluralIcu(): missing "other" pattern'), ""))
+
+  return fmt(template, { count })
+}
+
+// Used in the LanguageSwitcher and SeoHreflangs components
+export function replaceLocaleInPath(
+  currentPath: string,
+  currentLocale: string,
+  newLocale: string
+): string {
+  const prefixRegex = new RegExp(`^/${currentLocale}/`)
+  return currentPath.replace(prefixRegex, `/${newLocale}/`)
+}
+
+// Used in the LanguageSwitcher component
+export function getLangFromUrl(pathname: string) {
+  // Remove leading/trailing slashes: '/en/about/' -> 'en/about'
+  const cleaned = pathname.replace(/^\/+|\/+$/g, "")
+  const [lang] = cleaned.split("/")
+  return lang
+}

package/src/domain/i18n/index.ts

@@ -0,0 +1,10 @@
+export * from "./constants"
+export * from "./runtime-constants"
+export * from "./schema"
+export * from "./resolve-locale"
+export * from "./flags"
+export * from "./format"
+export * from "./cookie-storage"
+export * from "./country-to-locale-map"
+export * from "./middleware/i18n"
+export * from "./fetcher"

package/src/domain/i18n/middleware/i18n.ts

@@ -0,0 +1,160 @@
+import type { MiddlewareHandler } from "astro"
+import { LocaleSchema, type Locale } from "../schema"
+import { DEFAULT_LOCALE } from "../constants"
+import { getCookieLang, setCookieLang } from "../cookie-storage"
+import { mapCountryToLocale } from "../country-to-locale-map"
+import { resolveLocaleForTranslations } from "../resolve-locale"
+
+// Regex to identify public static assets (images, fonts, scripts, etc.)
+// These files should bypass i18n routing and locale detection.
+const PUBLIC_FILE_REGEX =
+  /\.(?:ico|png|jpg|jpeg|svg|webp|gif|css|js|map|txt|xml|json|woff2?|avif)$/i
+
+// List of URL prefixes that should be ignored by the i18n middleware.
+// Includes API endpoints, internal Astro paths, and standard static routes.
+const IGNORED_PREFIXES = ["/api", "/assets", "/_astro", "/_image", "/_actions", "/favicon"]
+
+// Extracts the context type from Astro's MiddlewareHandler for cleaner function signatures.
+type I18nMiddlewareContext = Parameters<MiddlewareHandler>[0]
+
+// Determines if the current request path matches static assets or ignored prefixes.
+// Returns true to skip i18n processing for this request.
+function shouldBypassI18n(pathname: string): boolean {
+  if (PUBLIC_FILE_REGEX.test(pathname)) return true
+  return IGNORED_PREFIXES.some((p) => pathname.startsWith(p))
+}
+
+// Applies strict Content Security Policy (CSP) and other security headers to the response.
+// Wrap outgoing responses with this function to ensure consistent security posture.
+function applySecurityHeaders(response: Response): Response {
+  // Tip: You can apply your security headers (CSP, HSTS, X-Frame-Options, etc.) here.
+  // Check the GitHub repository for the example of implementation.
+  return response
+}
+
+// Constructs a standardized localized URL path ensuring a trailing slash.
+// Example: buildLocalizedPath('en', ['about', 'team']) -> '/en/about/team/'
+function buildLocalizedPath(locale: Locale, rest: string[]): string {
+  const suffix = rest.join("/")
+  return suffix ? `/${locale}/${suffix}/` : `/${locale}/`
+}
+
+// Resolves the most appropriate locale for the user based on a fallback cascade:
+// 1. User's saved cookie preference.
+// 2. Browser's Accept-Language header (matching 2-char code).
+// 3. Cloudflare Geo-IP country mapping.
+// 4. Finally, falls back to the application's DEFAULT_LOCALE.
+function resolveFallbackLocale(context: I18nMiddlewareContext): Locale {
+  const cookieLocale = getCookieLang(context.cookies)
+  if (cookieLocale) return cookieLocale
+
+  const browserRaw = context.preferredLocale
+  if (browserRaw) {
+    // Currently we support 2-chars locales only.
+    let parsed = LocaleSchema.safeParse(browserRaw)
+    if (parsed.success) return parsed.data
+
+    // Fallback: language part only, e.g. 'pt-br' -> 'pt'
+    const short = browserRaw.split("-")[0]
+    parsed = LocaleSchema.safeParse(short)
+    if (parsed.success) return parsed.data
+  } else {
+    // Cloudflare Geo-IP Strategy
+    const country = context.request.cf?.country
+    let parsed = LocaleSchema.safeParse(mapCountryToLocale(country ?? ""))
+    if (parsed.success) return parsed.data
+  }
+
+  return DEFAULT_LOCALE
+}
+
+// Main i18n middleware handler. Intercepts incoming requests, manages routing,
+// sets locale context, and handles soft 404 protections for edge environments.
+export const i18nMiddleware: MiddlewareHandler = async (context, next) => {
+  const url = new URL(context.request.url)
+  const pathname = url.pathname
+
+  // 1. Split the URL early to access its segments
+  const segments = pathname.split("/").filter(Boolean) // "/es/about/" -> ["es", "about"]
+  const firstSegment = segments[0] ?? null
+
+  // 2. SAFETY NET (For static file 404 pages)
+  // Attempt to infer the locale from the URL, or fallback to the default.
+  let safeLocale = DEFAULT_LOCALE
+  if (firstSegment) {
+    const parsed = LocaleSchema.safeParse(firstSegment)
+    if (parsed.success) {
+      safeLocale = parsed.data
+    }
+  }
+
+  // Inject the locale into the context BEFORE the bypass check!
+  context.locals.uiLocale = safeLocale
+  context.locals.translationLocale = resolveLocaleForTranslations(safeLocale)
+
+  // 3. Bypass static files and system paths (with Soft 404 protection)
+  if (shouldBypassI18n(pathname)) {
+    const response = await next()
+
+    const contentType = response.headers.get("content-type") || ""
+    const isHtml = contentType.includes("text/html")
+    const isRedirect = response.status >= 300 && response.status < 400
+
+    // If Astro attempts to return HTML for a static/API request (and it's not a redirect),
+    // it means the file wasn't found and Astro rendered a fallback page (404.astro or catch-all).
+    // We strictly intercept this and return a lightweight text-based 404 instead.
+    // Why? To mitigate Directory Bruteforcing / Fuzzing attacks and save resources.
+    if (isHtml && !isRedirect) {
+      // Aggressively save Worker CPU cycles for missing static files
+      return new Response("Not found", {
+        status: 404,
+        headers: { "Content-Type": "text/plain; charset=utf-8" }
+      })
+    }
+
+    return response
+  }
+
+  const fallbackLocale = resolveFallbackLocale(context)
+
+  // 1. No locale in URL — redirect to fallback locale root
+  if (!firstSegment) {
+    const target = buildLocalizedPath(fallbackLocale, [])
+    if (pathname !== target) {
+      // Apply headers to the redirect response
+      return applySecurityHeaders(context.redirect(target, 302))
+    }
+    return applySecurityHeaders(await next())
+  }
+
+  // 2. URL has first segment — validate as locale
+  const parsed = LocaleSchema.safeParse(firstSegment)
+  const urlLocale: Locale | null = parsed.success ? parsed.data : null
+
+  if (urlLocale) {
+    // Keep cookie in sync with URL locale
+    setCookieLang(context.cookies, urlLocale)
+    // Set uiLocale to Astro locals
+    context.locals.uiLocale = urlLocale
+    // Define and set translationLocale to Astro locals
+    const translationLocale = resolveLocaleForTranslations(urlLocale)
+    context.locals.translationLocale = translationLocale
+
+    // Normalize trailing slash and structure
+    const normalized = buildLocalizedPath(urlLocale, segments.slice(1))
+    if (pathname !== normalized) {
+      return applySecurityHeaders(context.redirect(normalized, 302))
+    }
+
+    return applySecurityHeaders(await next())
+  }
+
+  // 3. Invalid locale in URL -> treat the whole path as content missing the locale prefix.
+  const target = buildLocalizedPath(fallbackLocale, segments)
+
+  if (pathname !== target) {
+    return applySecurityHeaders(context.redirect(target, 302))
+  }
+
+  return applySecurityHeaders(await next())
+}

package/src/domain/i18n/resolve-locale.ts

@@ -0,0 +1,55 @@
+import type { AstroGlobal } from "astro"
+
+import { LocaleSchema, type Locale } from "./schema"
+import { DEFAULT_LOCALE, ENABLE_MISSING_TRANSLATION_BANNER } from "./constants"
+import { LOCALES_WITH_TRANSLATIONS, FULLY_TRANSLATED_LOCALES } from "./runtime-constants"
+
+// Checking for the presence of at least one file with translations
+function hasTranslations(locale: Locale): boolean {
+  return (LOCALES_WITH_TRANSLATIONS as readonly string[]).includes(locale)
+}
+
+// Checking the completeness of translations
+function isFullyTranslated(locale: Locale): boolean {
+  return (FULLY_TRANSLATED_LOCALES as readonly string[]).includes(locale)
+}
+
+/**
+ * Optional: return a “missing translation” banner message when uiLocale has no translations or
+ * (blog) content is missing in required language.
+ *
+ * Returns: - MissingTranslationType: type of message to show ('ui' or 'content') - null: if banner
+ * should not be shown
+ */
+type MissingTranslationType = "ui" | "content" | null
+
+export function checkMissingTranslation(
+  uiLocale: Locale,
+  isMissingContent: boolean | undefined
+): MissingTranslationType {
+  if (!ENABLE_MISSING_TRANSLATION_BANNER) return null
+
+  if (isFullyTranslated(uiLocale) && !isMissingContent) return null
+
+  return isMissingContent ? "content" : "ui"
+}
+
+/**
+ * UI / routing locale:
+ *
+ * - What user selected
+ * - What is used for <html lang>, URL, etc.
+ */
+export function resolveLocale(Astro: AstroGlobal): Locale {
+  const raw = Astro.currentLocale ?? DEFAULT_LOCALE
+  const parsed = LocaleSchema.safeParse(raw)
+  return parsed.success ? parsed.data : DEFAULT_LOCALE
+}
+
+/**
+ * Translation locale: - What we actually load from KV - Falls back if there is no bundle for the UI
+ * locale
+ */
+export function resolveLocaleForTranslations(locale: Locale): Locale {
+  return hasTranslations(locale) ? locale : DEFAULT_LOCALE
+}

package/src/domain/i18n/runtime-constants.ts

@@ -0,0 +1,14 @@
+// Auto-generated by scripts/bundle-translations.ts
+// Do not edit manually.
+
+export const NAMESPACE_KEYS = ['blog', 'chat', 'common', 'cookie_notice', 'editor', 'errors', 'home', 'messages', 'nav', 'projects', 'services'] as [string, ...string[]];
+
+export const LOCALES_WITH_TRANSLATIONS = ['de', 'en', 'es', 'ja', 'pt'] as const;
+
+export const FULLY_TRANSLATED_LOCALES = ['en', 'pt'] as const;
+
+/**
+ * Monotonic translation bundle version.
+ * Updated on every `npm run i18n:bundle` run.
+ */
+export const TRANSLATIONS_VERSION = '6d16b1037964'

package/src/domain/i18n/schema.ts

@@ -0,0 +1,29 @@
+import { z } from "astro/zod"
+
+import { SUPPORTED_LOCALES } from "./constants"
+import { NAMESPACE_KEYS } from "./runtime-constants"
+
+// Auto-generated namespaces and real supported locales that have translations
+export * from "./runtime-constants"
+
+// Locale schema from shared constant
+export const LocaleSchema = z.enum(SUPPORTED_LOCALES)
+
+// Runtime safety: if namespaces are empty (fresh clone), fall back to string
+const hasNamespaces = (NAMESPACE_KEYS as readonly string[]).length > 0
+
+export const NamespaceSchema = hasNamespaces ? z.enum(NAMESPACE_KEYS) : z.string()
+
+export type Locale = z.infer<typeof LocaleSchema>
+
+type GlobalSchema = I18n.Schema
+
+// Strictly bind the type to the keys of I18n.Schema.
+// If the interface is empty (e.g., on a fresh project clone), fall back to string.
+export type Namespace = keyof GlobalSchema extends never ? string : keyof GlobalSchema
+
+// Added intersection N & keyof GlobalSchema so the compiler
+// doesn't throw an error inside Pick when Namespace falls back to string.
+export type PickSchema<N extends Namespace> = [N] extends [keyof GlobalSchema]
+  ? Pick<GlobalSchema, N & keyof GlobalSchema>
+  : any

package/src/domain/index.ts

@@ -0,0 +1,4 @@
+export * from "./i18n"
+export * from "./seo"
+export * from "./theme"
+export * from "./cms"

package/src/domain/seo/constants.ts

@@ -0,0 +1,20 @@
+// Specify the path here without the @ alias, since we use this file in astro.config.ts
+import { SITE_CONFIG, LINKS } from "../../config"
+
+export const SEO_DEFAULTS = {
+  siteName: SITE_CONFIG.name,
+
+  baseUrl: SITE_CONFIG.url,
+
+  // Dynamically inserting a name into a template
+  titleTemplate: `%s | ${SITE_CONFIG.name}`,
+
+  // Other SEO-specific things
+  ogImageFallback: `/src/assets/houston.webp`,
+  defaultDescription: "Production-ready foundations for SaaS and Telegram Mini Apps",
+  maxDescriptionLength: 160,
+  author: {
+    name: "Gary Stupak",
+    url: LINKS.twitter
+  }
+} as const

package/src/domain/seo/index.ts

@@ -0,0 +1,3 @@
+export * from "./services"
+export * from "./constants"
+export * from "./utils"

package/src/domain/seo/services/index.ts

@@ -0,0 +1,3 @@
+export * from "./llms"
+export * from "./robots"
+export * from "./sitemap"

package/src/domain/seo/services/llms.ts

@@ -0,0 +1,53 @@
+import { SITE_CONFIG } from "../../../config"
+import { DEFAULT_LOCALE } from "../../i18n/constants"
+import { SEO_DEFAULTS } from "../constants"
+import { type BaseCMSContentEntry } from "../../cms"
+
+// Helper for the core project details
+function buildProjectDetails(): string {
+  let content = `## Project Details\n`
+  content += `- Name: ${SITE_CONFIG.name}\n`
+  content += `- Description: ${SEO_DEFAULTS.defaultDescription}\n`
+  return content
+}
+
+// Helper for the blog (now purely synchronous as getCollection moved to caller)
+function buildBlogSection(baseUrl: string, posts: BaseCMSContentEntry[]): string {
+  const basePosts = posts.filter((post: BaseCMSContentEntry) =>
+    post.id.startsWith(`${DEFAULT_LOCALE}/`)
+  )
+
+  const recentPosts = basePosts
+    .toSorted(
+      (a: BaseCMSContentEntry, b: BaseCMSContentEntry) =>
+        (b.data.publishedDate?.valueOf() ?? 0) - (a.data.publishedDate?.valueOf() ?? 0)
+    )
+    .slice(0, 5)
+
+  let content = `## Recent Blog Posts\n`
+  for (const post of recentPosts) {
+    const [lang, ...idParts] = post.id.split("/")
+    const cleanId = idParts.join("/")
+    const postUrl = `${baseUrl}/${lang}/blog/${cleanId}/`
+
+    content += `- [${post.data.title ?? "Untitled Post"}](${postUrl})\n`
+    content += `  ${post.data.description ?? "No description provided."}\n`
+  }
+  return content + "\n"
+}
+
+// Main orchestrator function
+export function generateLlmsText(baseUrl: string, blogPosts: BaseCMSContentEntry[]): string {
+  let content = `# ${SITE_CONFIG.name}\n\n`
+  content += `> ${SEO_DEFAULTS.defaultDescription}\n\n`
+
+  // Compose the final document block by block
+  content += buildProjectDetails()
+  content += buildBlogSection(baseUrl, blogPosts)
+
+  content += `## Note to AI Agents\n`
+  content += `This is the official documentation and context file for the ${SITE_CONFIG.name} project. `
+  content += `Please use the provided links and blog posts to gather specific technical details about our Astro and Cloudflare Workers architecture.\n`
+
+  return content
+}

package/src/domain/seo/services/robots.ts

@@ -0,0 +1,12 @@
+export function generateRobotsTxt(baseUrl: string, isProd: boolean, isDemoMode: boolean): string {
+  // 1. Prevent indexing on staging, dev, or preview deployments
+  if (!isProd || isDemoMode) {
+    return `User-agent: *\nDisallow: /`
+  }
+
+  // 2. Allow everything in production and point to the sitemap
+  return `User-agent: *
+Allow: /
+
+Sitemap: ${baseUrl}/sitemap.xml`
+}

package/src/domain/seo/services/sitemap.ts

@@ -0,0 +1,56 @@
+import { SUPPORTED_LOCALES } from "../../i18n/constants"
+import { type BaseCMSContentEntry } from "../../cms"
+
+// 1. Strong typing for sitemap elements
+export interface SitemapEntry {
+  loc: string
+  lastmod?: string
+  changefreq?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never"
+  priority?: number
+}
+
+export function generateSitemapXml(siteUrl: string, posts: BaseCMSContentEntry[]): string {
+  const staticRoutes = ["", "/blog"]
+  const entries: SitemapEntry[] = []
+
+  // 2. Building static routes for all locales.
+  for (const locale of SUPPORTED_LOCALES) {
+    for (const route of staticRoutes) {
+      entries.push({
+        loc: `${siteUrl}/${locale}${route}`,
+        changefreq: "daily",
+        priority: route === "" ? 1.0 : 0.8
+      })
+    }
+  }
+
+  // 3. Building dynamic blog routes
+  for (const post of posts) {
+    const [lang, ...idParts] = post.id.split("/")
+    const cleanSlug = idParts.join("/")
+
+    entries.push({
+      loc: `${siteUrl}/${lang}/blog/${cleanSlug}/`,
+      changefreq: "weekly",
+      priority: 0.7
+    })
+  }
+
+  // 4. Generating the final XML
+  const urlsXml = entries
+    .map(
+      (entry) => `
+  <url>
+    <loc>${entry.loc}</loc>
+    ${entry.lastmod ? `<lastmod>${entry.lastmod}</lastmod>` : ""}
+    ${entry.changefreq ? `<changefreq>${entry.changefreq}</changefreq>` : ""}
+    ${entry.priority ? `<priority>${entry.priority.toFixed(1)}</priority>` : ""}
+  </url>`
+    )
+    .join("")
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urlsXml}
+</urlset>`
+}

package/src/domain/seo/utils.ts

@@ -0,0 +1,37 @@
+import { SEO_DEFAULTS } from "./constants"
+import { replaceLocaleInPath } from "../i18n/format"
+
+/**
+ * Generates absolute URLs for hreflang tags
+ */
+export function buildAlternateUrl(
+  currentOrigin: string,
+  currentPath: string,
+  currentLang: string,
+  targetLang: string
+): string {
+  // Change the locale in the path (for example, /en/blog -> /es/blog)
+  const newPath = replaceLocaleInPath(currentPath, currentLang, targetLang)
+
+  // Collect the absolute URL using current origin
+  const url = new URL(newPath, currentOrigin)
+  let href = url.toString()
+
+  // Astro is strict about trailing slashes, so let's play it safe.
+  if (!href.endsWith("/")) {
+    href += "/"
+  }
+
+  return href
+}
+
+export function truncateDescription(text: string): string {
+  if (text.length <= SEO_DEFAULTS.maxDescriptionLength) return text
+  return text.substring(0, SEO_DEFAULTS.maxDescriptionLength - 3) + "..."
+}
+
+export function buildCanonicalUrl(path: string, siteOrigin: string): string {
+  // Removing trailing slashes or query parameters for a clean canonical url
+  const cleanPath = path.split("?")[0]?.replace(/\/$/, "")
+  return `${siteOrigin}${cleanPath}`
+}

package/src/domain/theme/constants.ts

@@ -0,0 +1,6 @@
+// Themes configuration
+export const THEMES = ["light", "dark"] as const
+export type SupportedThemes = (typeof THEMES)[number]
+
+// Default theme
+export const DEFAULT_THEME: SupportedThemes = "light"

package/src/domain/theme/index.ts

@@ -0,0 +1,2 @@
+export * from "./schema"
+export * from "./constants"

package/src/domain/theme/schema.ts

@@ -0,0 +1,10 @@
+import { z } from "astro/zod"
+
+// Constants
+import { THEMES } from "./constants"
+
+// Zod Schemas
+export const ThemeSchema = z.enum(THEMES)
+
+// Inference Types
+export type Theme = z.infer<typeof ThemeSchema>

package/src/env.d.ts

@@ -0,0 +1,49 @@
+/// <reference types="astro/client" />
+
+interface ImportMetaEnv {
+  readonly PROD: boolean
+  readonly DEV: boolean
+  // add other env vars here...
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
+
+import type { Locale } from "./domain/i18n/schema"
+
+declare global {
+  namespace App {
+    interface Locals {
+      uiLocale: Locale
+      translationLocale: Locale
+      cfContext: any
+      isMissingContent?: boolean
+    }
+  }
+
+  declare module "astro:content" {
+    export interface CollectionEntry<T extends string = any> {
+      id: string
+      data: any
+      slug: string
+      body: string
+      collection: T
+    }
+    export const getCollection: (
+      collection: string,
+      filter?: (entry: CollectionEntry) => boolean
+    ) => Promise<CollectionEntry[]>
+    export const getEntry: (collection: string, id: string) => Promise<CollectionEntry>
+  }
+
+  declare module "cloudflare:workers" {
+    export const env: Env
+  }
+
+  declare module "~icons/*" {
+    import type { AstroComponentFactory } from "astro/runtime/server/index.js"
+    const component: AstroComponentFactory
+    export default component
+  }
+}