jamdesk 1.1.91 → 1.1.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.91",
+  "version": "1.1.92",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",

package/vendored/components/navigation/LanguageSelector.tsx

@@ -14,6 +14,7 @@ import {
   toHreflang,
 } from '@/lib/language-utils';
 import { useLinkPrefix } from '@/lib/link-prefix-context';
+import { useProjectSlug } from '@/lib/project-slug-context';
 import { getUiStrings } from '@/lib/ui-strings';
 
 interface LanguageSelectorProps {
@@ -35,6 +36,7 @@ export function LanguageSelector({
 }: LanguageSelectorProps) {
   const router = useRouter();
   const linkPrefix = useLinkPrefix();
+  const projectSlug = useProjectSlug();
   const pathname = usePathname() ?? '';
   const ui = getUiStrings(extractLanguageFromPath(pathname || '/'));
   const [isOpen, setIsOpen] = useState(false);
@@ -83,7 +85,7 @@ export function LanguageSelector({
   // fight the user's in-session navigation choices (they may have explicitly
   // switched languages this session, which we don't want to revert).
   useEffect(() => {
-    const savedPref = getLanguagePreference();
+    const savedPref = getLanguagePreference(projectSlug);
     if (savedPref && currentLanguage && savedPref !== currentLanguage.code) {
       // Only redirect if on default language URL (no explicit language in path)
       const hasLangInPath = languages.some(
@@ -117,7 +119,7 @@ export function LanguageSelector({
         return;
       }
 
-      saveLanguagePreference(lang.code);
+      saveLanguagePreference(lang.code, projectSlug);
 
       const basePath = transformLanguagePath(
         pathname || '/docs',
@@ -130,7 +132,7 @@ export function LanguageSelector({
       onNavigate(url);
       router.push(url);
     },
-    [isNavigating, currentLanguage?.code, actualDefault, pathname, linkPrefix, router, onNavigate]
+    [isNavigating, currentLanguage?.code, actualDefault, pathname, linkPrefix, router, onNavigate, projectSlug]
   );
 
   // Handle keyboard navigation

package/vendored/lib/language-utils.ts

@@ -419,17 +419,28 @@ export function resolveLocaleWithLoweredSet(
 }
 
 /**
- * localStorage key for language preference
+ * localStorage key prefix for project-scoped language preferences. The actual
+ * key is `${LANGUAGE_STORAGE_KEY_PREFIX}${slug}`. Scoping by project prevents
+ * a `cn` preference saved on Project A from forcing a `/cn/...` redirect on
+ * Project B that only declares `zh-Hans` (would 404).
  */
-export const LANGUAGE_STORAGE_KEY = 'jamdesk-language-preference';
+export const LANGUAGE_STORAGE_KEY_PREFIX = 'jamdesk-language-preference:';
+
+/** Legacy unscoped key — read-once for one-time migration to per-project storage. */
+const LEGACY_LANGUAGE_STORAGE_KEY = 'jamdesk-language-preference';
+
+function storageKey(projectSlug: string): string {
+  return `${LANGUAGE_STORAGE_KEY_PREFIX}${projectSlug}`;
+}
 
 /**
- * Save language preference to localStorage
- * Handles private browsing mode gracefully
+ * Save language preference to localStorage, scoped to project slug.
+ * Handles private browsing mode gracefully.
  */
-export function saveLanguagePreference(code: LanguageCode): void {
+export function saveLanguagePreference(code: LanguageCode, projectSlug: string): void {
+  if (!projectSlug) return;
   try {
-    localStorage.setItem(LANGUAGE_STORAGE_KEY, code);
+    localStorage.setItem(storageKey(projectSlug), code);
   } catch {
     // localStorage not available (private browsing, etc.)
     // Fail silently
@@ -437,15 +448,24 @@ export function saveLanguagePreference(code: LanguageCode): void {
 }
 
 /**
- * Get saved language preference from localStorage
- * Returns undefined if not set or localStorage unavailable
+ * Get saved language preference for a project from localStorage.
+ * Returns undefined if not set or localStorage unavailable.
  */
-export function getLanguagePreference(): LanguageCode | undefined {
+export function getLanguagePreference(projectSlug: string): LanguageCode | undefined {
+  if (!projectSlug) return undefined;
   try {
-    const saved = localStorage.getItem(LANGUAGE_STORAGE_KEY);
+    const saved = localStorage.getItem(storageKey(projectSlug));
     if (saved && isValidLanguageCode(saved)) {
       return saved as LanguageCode;
     }
+    // One-time read of legacy unscoped key — promotes it to the per-project
+    // slot the first time a returning user visits and clears the legacy entry.
+    const legacy = localStorage.getItem(LEGACY_LANGUAGE_STORAGE_KEY);
+    if (legacy && isValidLanguageCode(legacy)) {
+      localStorage.setItem(storageKey(projectSlug), legacy);
+      localStorage.removeItem(LEGACY_LANGUAGE_STORAGE_KEY);
+      return legacy as LanguageCode;
+    }
   } catch {
     // localStorage not available
   }
@@ -453,11 +473,12 @@ export function getLanguagePreference(): LanguageCode | undefined {
 }
 
 /**
- * Clear saved language preference
+ * Clear saved language preference for a project.
  */
-export function clearLanguagePreference(): void {
+export function clearLanguagePreference(projectSlug: string): void {
+  if (!projectSlug) return;
   try {
-    localStorage.removeItem(LANGUAGE_STORAGE_KEY);
+    localStorage.removeItem(storageKey(projectSlug));
   } catch {
     // localStorage not available
   }

package/vendored/lib/seo.ts

@@ -188,7 +188,7 @@ function getLanguagePagePaths(langConfig: LanguageConfig): Set<string> {
  * @param languages - Array of language configurations from docs.json
  * @returns Record of language code to URL for alternates.languages
  */
-function buildHreflangAlternates(
+export function buildHreflangAlternates(
   baseUrl: string,
   pagePath: string,
   languages: LanguageConfig[]

package/vendored/lib/static-artifacts.ts

@@ -5,7 +5,7 @@
  * for ISR projects. These are uploaded to R2 alongside the MDX content.
  */
 
-import type { NavigationConfig } from './docs-types.js';
+import type { NavigationConfig, LanguageConfig } from './docs-types.js';
 import { RECURSE_KEYS } from './enhance-navigation.js';
 import { filterVisibility } from './visibility-filter.js';
 import {
@@ -13,6 +13,7 @@ import {
   resolveLocaleFromPath,
   resolveLocaleWithLoweredSet,
 } from './language-utils.js';
+import { buildHreflangAlternates } from './seo.js';
 
 /**
  * Page metadata for artifact generation.
@@ -44,6 +45,13 @@ export interface SitemapOptions {
   hostAtDocs?: boolean;
   /** Block all crawlers - generates empty sitemap */
   noindex?: boolean;
+  /**
+   * Language configurations from docs.json navigation. When provided, the
+   * sitemap emits `<xhtml:link rel="alternate" hreflang>` siblings per URL
+   * for every language that declares the page — Google's recommended sitemap
+   * localization signal (in addition to in-page hreflang link tags).
+   */
+  languages?: LanguageConfig[];
 }
 
 /**
@@ -53,7 +61,7 @@ export interface SitemapOptions {
  * @returns XML string
  */
 export function generateSitemap(options: SitemapOptions): string {
-  const { baseUrl, pages, hostAtDocs = false, noindex = false } = options;
+  const { baseUrl, pages, hostAtDocs = false, noindex = false, languages } = options;
 
   if (noindex) {
     return `<?xml version="1.0" encoding="UTF-8"?>
@@ -62,6 +70,11 @@ export function generateSitemap(options: SitemapOptions): string {
   }
 
   const urlPrefix = hostAtDocs ? '/docs' : '';
+  const hreflangBaseUrl = hostAtDocs ? `${baseUrl}/docs` : baseUrl;
+  const multiLang = languages && languages.length > 1;
+  const urlsetAttrs = multiLang
+    ? 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml"'
+    : 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"';
 
   const entries = pages
     .filter(p => !p.noindex && !p.hidden)
@@ -70,16 +83,32 @@ export function generateSitemap(options: SitemapOptions): string {
       const lastmod = p.lastModified || new Date().toISOString().split('T')[0];
       const priority = p.path === 'introduction' ? '1.0' : '0.8';
 
+      // Per Google's spec, emit hreflang siblings only when the page has
+      // translations. buildHreflangAlternates already filters to languages
+      // whose navigation declares this page, so we won't point at 404s.
+      let hreflangLinks = '';
+      if (multiLang) {
+        const alternates = buildHreflangAlternates(hreflangBaseUrl, p.path, languages);
+        if (alternates) {
+          hreflangLinks = Object.entries(alternates)
+            .map(
+              ([tag, href]) =>
+                `\n    <xhtml:link rel="alternate" hreflang="${tag}" href="${href}"/>`,
+            )
+            .join('');
+        }
+      }
+
       return `  <url>
     <loc>${url}</loc>
     <lastmod>${lastmod}</lastmod>
     <changefreq>weekly</changefreq>
-    <priority>${priority}</priority>
+    <priority>${priority}</priority>${hreflangLinks}
   </url>`;
     });
 
   return `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<urlset ${urlsetAttrs}>
 ${entries.join('\n')}
 </urlset>`;
 }
@@ -353,6 +382,8 @@ export interface GenerateAllOptions {
   rssPages?: RssPageInfo[];
   /** Pages with full content (for llms-full.txt generation) */
   llmsFullPages?: LlmsFullPageInfo[];
+  /** Language configurations (forwarded to sitemap for hreflang siblings) */
+  languages?: LanguageConfig[];
 }
 
 /**
@@ -374,10 +405,10 @@ export interface GeneratedArtifacts {
  */
 export function generateAllArtifacts(options: GenerateAllOptions): GeneratedArtifacts {
   const {
-    baseUrl, name, description, pages, hostAtDocs, noindex, rssPages, llmsFullPages,
+    baseUrl, name, description, pages, hostAtDocs, noindex, rssPages, llmsFullPages, languages,
   } = options;
 
-  const sitemap = generateSitemap({ baseUrl, pages, hostAtDocs, noindex });
+  const sitemap = generateSitemap({ baseUrl, pages, hostAtDocs, noindex, languages });
   const llmsTxt = generateLlmsTxt({
     name, description, baseUrl, pages, hostAtDocs, noindex,
   });