jamdesk 1.1.144 → 1.1.145

package/dist/lib/normalize-config.d.ts

@@ -12,19 +12,23 @@
  * Field mappings:
  * - modeToggle.default -> appearance.default
  * - modeToggle.isHidden -> appearance.strict
- * - metadata -> seo.metatags
+ * - metadata.timestamp -> config.metadata.timestamp (real feature flag, kept)
+ * - metadata.<other> -> seo.metatags (legacy Mintlify metatags, deprecated)
  * - navbar.style -> preserved but ignored in rendering
  * - layout -> removed (theme determines layout)
  */
 /**
- * Input config type for normalization
+ * Input config type for normalization.
+ *
+ * `metadata` is overloaded for backward compatibility: historically a Mintlify
+ * metatags string-map, it now also carries the real `timestamp` feature flag.
  */
 interface ConfigInput {
     modeToggle?: {
         default?: 'dark' | 'light';
         isHidden?: boolean;
     };
-    metadata?: Record<string, string>;
+    metadata?: Record<string, unknown>;
     layout?: string;
     appearance?: unknown;
     seo?: {

package/dist/lib/normalize-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-config.d.ts","sourceRoot":"","sources":["../../src/lib/normalize-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;GAEG;AACH,UAAU,WAAW;IACnB,UAAU,CAAC,EAAE;QACX,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE;QACJ,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,MAAM,CAAC,EAAE;QACP,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAiDpE"}
+{"version":3,"file":"normalize-config.d.ts","sourceRoot":"","sources":["../../src/lib/normalize-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;GAKG;AACH,UAAU,WAAW;IACnB,UAAU,CAAC,EAAE;QACX,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE;QACJ,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,MAAM,CAAC,EAAE;QACP,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CA4DpE"}

package/dist/lib/normalize-config.js

@@ -12,7 +12,8 @@
  * Field mappings:
  * - modeToggle.default -> appearance.default
  * - modeToggle.isHidden -> appearance.strict
- * - metadata -> seo.metatags
+ * - metadata.timestamp -> config.metadata.timestamp (real feature flag, kept)
+ * - metadata.<other> -> seo.metatags (legacy Mintlify metatags, deprecated)
  * - navbar.style -> preserved but ignored in rendering
  * - layout -> removed (theme determines layout)
  */
@@ -38,17 +39,26 @@ export function normalizeConfig(config) {
             };
         }
     }
-    // 2. Normalize metadata -> seo.metatags
+    // 2. Normalize metadata.
+    //    - `timestamp` is a real page-metadata feature flag -> config.metadata.timestamp.
+    //    - any OTHER keys are legacy Mintlify metatags -> seo.metatags (deprecated).
     if (metadata) {
-        warnings.push('metadata is deprecated. Use seo: { metatags: { ... } } instead.');
-        const existingMetatags = normalized.seo?.metatags || {};
-        normalized.seo = {
-            ...normalized.seo,
-            metatags: {
-                ...metadata,
-                ...existingMetatags,
-            },
-        };
+        const { timestamp, ...legacyMetatags } = metadata;
+        if (timestamp !== undefined) {
+            normalized.metadata = { timestamp: timestamp === true };
+        }
+        const legacyKeys = Object.keys(legacyMetatags);
+        if (legacyKeys.length > 0) {
+            warnings.push('metadata is deprecated. Use seo: { metatags: { ... } } instead.');
+            const existingMetatags = normalized.seo?.metatags || {};
+            normalized.seo = {
+                ...normalized.seo,
+                metatags: {
+                    ...legacyMetatags,
+                    ...existingMetatags,
+                },
+            };
+        }
     }
     // 3. Warn about layout
     if (layout) {

package/dist/lib/normalize-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-config.js","sourceRoot":"","sources":["../../src/lib/normalize-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgCH;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAmB;IACjD,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;IACzD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,MAAM,UAAU,GAAgB,EAAE,GAAG,IAAI,EAAE,CAAC;IAE5C,wCAAwC;IACxC,IAAI,UAAU,EAAE,CAAC;QACf,QAAQ,CAAC,IAAI,CACX,sFAAsF,CACvF,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YACvB,UAAU,CAAC,UAAU,GAAG;gBACtB,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,QAAQ;gBACvC,MAAM,EAAE,UAAU,CAAC,QAAQ,KAAK,IAAI;aACrC,CAAC;QACJ,CAAC;IACH,CAAC;IAED,wCAAwC;IACxC,IAAI,QAAQ,EAAE,CAAC;QACb,QAAQ,CAAC,IAAI,CACX,iEAAiE,CAClE,CAAC;QACF,MAAM,gBAAgB,GAAI,UAAU,CAAC,GAAW,EAAE,QAAQ,IAAI,EAAE,CAAC;QACjE,UAAU,CAAC,GAAG,GAAG;YACf,GAAG,UAAU,CAAC,GAAG;YACjB,QAAQ,EAAE;gBACR,GAAG,QAAQ;gBACX,GAAG,gBAAgB;aACpB;SACF,CAAC;IACJ,CAAC;IAED,uBAAuB;IACvB,IAAI,MAAM,EAAE,CAAC;QACX,QAAQ,CAAC,IAAI,CACX,oGAAoG,CACrG,CAAC;IACJ,CAAC;IAED,6BAA6B;IAC7B,IAAI,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;QACvB,QAAQ,CAAC,IAAI,CACX,6DAA6D,CAC9D,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC;AAC1C,CAAC"}
+{"version":3,"file":"normalize-config.js","sourceRoot":"","sources":["../../src/lib/normalize-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAmCH;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAmB;IACjD,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;IACzD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,MAAM,UAAU,GAAgB,EAAE,GAAG,IAAI,EAAE,CAAC;IAE5C,wCAAwC;IACxC,IAAI,UAAU,EAAE,CAAC;QACf,QAAQ,CAAC,IAAI,CACX,sFAAsF,CACvF,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YACvB,UAAU,CAAC,UAAU,GAAG;gBACtB,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,QAAQ;gBACvC,MAAM,EAAE,UAAU,CAAC,QAAQ,KAAK,IAAI;aACrC,CAAC;QACJ,CAAC;IACH,CAAC;IAED,yBAAyB;IACzB,sFAAsF;IACtF,iFAAiF;IACjF,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,EAAE,SAAS,EAAE,GAAG,cAAc,EAAE,GAAG,QAAQ,CAAC;QAElD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,UAAU,CAAC,QAAQ,GAAG,EAAE,SAAS,EAAE,SAAS,KAAK,IAAI,EAAE,CAAC;QAC1D,CAAC;QAED,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC/C,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,QAAQ,CAAC,IAAI,CACX,iEAAiE,CAClE,CAAC;YACF,MAAM,gBAAgB,GAAI,UAAU,CAAC,GAAW,EAAE,QAAQ,IAAI,EAAE,CAAC;YACjE,UAAU,CAAC,GAAG,GAAG;gBACf,GAAG,UAAU,CAAC,GAAG;gBACjB,QAAQ,EAAE;oBACR,GAAI,cAAyC;oBAC7C,GAAG,gBAAgB;iBACpB;aACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,uBAAuB;IACvB,IAAI,MAAM,EAAE,CAAC;QACX,QAAQ,CAAC,IAAI,CACX,oGAAoG,CACrG,CAAC;IACJ,CAAC;IAED,6BAA6B;IAC7B,IAAI,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;QACvB,QAAQ,CAAC,IAAI,CACX,6DAA6D,CAC9D,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC;AAC1C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.144",
+  "version": "1.1.145",
   "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/layout/BannerBar.tsx

@@ -0,0 +1,80 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import type { DocsConfig } from '@/lib/docs-types';
+import { useProjectSlug } from '@/lib/project-slug-context';
+import { renderInlineMarkdown } from '@/lib/inline-markdown';
+import { isBannerDismissed, dismissBanner } from '@/lib/banner-dismiss';
+
+/**
+ * Site-wide announcement bar pinned to the top of the page. Reads the global
+ * `banner` from docs.json. Renders nothing when absent, blank, or dismissed.
+ * Publishes its height to `--jd-banner-height` so the sticky header/sidebar can
+ * sit below it on mobile (where the page itself scrolls).
+ */
+export function BannerBar({ config }: { config: DocsConfig }) {
+  const content = config.banner?.content?.trim() ?? '';
+  const dismissible = config.banner?.dismissible === true;
+  const slug = useProjectSlug();
+  const [dismissed, setDismissed] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  // Sync dismissed state from storage after mount (keyed to the content hash).
+  // Only honor a stored dismissal when the banner is currently dismissible —
+  // otherwise a stale hash from a previous dismissible version of the same
+  // content would permanently hide a now-mandatory banner.
+  useEffect(() => {
+    if (content && dismissible) setDismissed(isBannerDismissed(slug, content));
+  }, [slug, content, dismissible]);
+
+  // Publish the banner height so the sticky header/sidebar can offset below it.
+  useEffect(() => {
+    const el = ref.current;
+    const root = document.documentElement;
+    if (!el || dismissed || !content) {
+      root.style.removeProperty('--jd-banner-height');
+      return;
+    }
+    const apply = () => root.style.setProperty('--jd-banner-height', `${el.offsetHeight}px`);
+    apply();
+    const ro = new ResizeObserver(apply);
+    ro.observe(el);
+    return () => {
+      ro.disconnect();
+      root.style.removeProperty('--jd-banner-height');
+    };
+  }, [dismissed, content]);
+
+  if (!content || dismissed) return null;
+
+  const handleDismiss = () => {
+    dismissBanner(slug, content);
+    setDismissed(true);
+  };
+
+  return (
+    <div
+      ref={ref}
+      data-jd-banner
+      role="region"
+      aria-label="Site announcement"
+      className="sticky top-0 z-50 w-full flex-shrink-0 bg-[var(--color-accent)] text-white"
+    >
+      <div className="mx-auto flex max-w-[1440px] items-center gap-3 px-6 py-2.5 text-sm">
+        <div className="flex-1 [&_a]:font-medium [&_a]:text-white [&_a]:underline">
+          {renderInlineMarkdown(content)}
+        </div>
+        {dismissible && (
+          <button
+            type="button"
+            onClick={handleDismiss}
+            aria-label="Dismiss announcement"
+            className="flex-shrink-0 cursor-pointer p-1 text-white/80 transition-colors hover:text-white"
+          >
+            <i className="fa-solid fa-xmark text-[16px]" aria-hidden="true" />
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}

package/vendored/components/layout/LayoutWrapper.tsx

@@ -7,6 +7,7 @@ import { TabsNav } from '@/components/navigation/TabsNav';
 import { LazyChatPanel } from '@/components/chat/LazyChatPanel';
 import { ChatResizeHandle } from '@/components/chat/ChatResizeHandle';
 import { ChatPanel } from '@/components/chat/ChatPanel';
+import { BannerBar } from '@/components/layout/BannerBar';
 import { ChatPanelProvider, useChatPanel } from '@/hooks/useChatPanel';
 import { useHashNavigation } from '@/hooks/useHashNavigation';
 import type { DocsConfig } from '@/lib/docs-types';
@@ -108,73 +109,81 @@ export function LayoutWrapper({ config, children, embed }: LayoutWrapperProps) {
     </ChatPanelProvider>
   );
 
-  // Sidebar-logo layout: Sidebar is full height, header only above content
+  // Sidebar-logo layout (Pulsar): Sidebar is full height, header only above
+  // content. Flex-column shell puts the banner above the fixed sidebar.
   if (layout === 'sidebar-logo') {
     return wrapWithProvider(
-      <div className="flex min-h-screen lg:h-screen lg:overflow-hidden">
-        <Sidebar
-          config={config}
-          layout={layout}
-          isOpen={isSidebarOpen}
-          onClose={closeSidebar}
-        />
-
-        <div className="flex-1 min-w-0 lg:ml-[295px] flex flex-col lg:h-screen bg-[var(--color-bg-content,var(--color-bg-primary))]">
-          <Header
+      <div className="flex flex-col min-h-screen lg:h-screen lg:overflow-hidden">
+        <BannerBar config={config} />
+        <div className="flex flex-1 min-h-0 lg:overflow-hidden">
+          <Sidebar
             config={config}
             layout={layout}
-            isSidebarOpen={isSidebarOpen}
-            onToggleSidebar={toggleSidebar}
+            isOpen={isSidebarOpen}
+            onClose={closeSidebar}
           />
-          <main
-            id="main-content"
-            className="flex-1 flex flex-col lg:min-h-0 transition-colors overflow-x-hidden"
-          >
-            {children}
-          </main>
-        </div>
 
-        {isDesktop && <DesktopChatColumn />}
-        {chatOverlay}
+          <div className="flex-1 min-w-0 lg:ml-[295px] flex flex-col lg:h-full bg-[var(--color-bg-content,var(--color-bg-primary))]">
+            <Header
+              config={config}
+              layout={layout}
+              isSidebarOpen={isSidebarOpen}
+              onToggleSidebar={toggleSidebar}
+            />
+            <main
+              id="main-content"
+              className="flex-1 flex flex-col lg:min-h-0 transition-colors overflow-x-hidden"
+            >
+              {children}
+            </main>
+          </div>
+
+          {isDesktop && <DesktopChatColumn />}
+          {chatOverlay}
+        </div>
       </div>,
     );
   }
 
-  // Header-logo layout (Jam, Nebula) — outer flex row for layout + chat column
+  // Header-logo layout (Jam, Nebula) — flex-column shell so the banner sits
+  // above everything full-bleed; the row below fills the remaining height.
   return wrapWithProvider(
-    <div className="flex min-h-screen lg:h-screen lg:overflow-hidden">
-      <div
-        className="flex-1 min-w-0 flex flex-col lg:overflow-hidden mx-auto px-4 lg:px-6"
-        style={{ maxWidth: 'var(--layout-max-width, none)' }}
-      >
-        <Header
-          config={config}
-          layout={layout}
-          isSidebarOpen={isSidebarOpen}
-          onToggleSidebar={toggleSidebar}
-        />
-
-        <TabsNav config={config} />
-
-        <div className="flex flex-1 lg:min-h-0">
-          <Sidebar
+    <div className="flex flex-col min-h-screen lg:h-screen lg:overflow-hidden">
+      <BannerBar config={config} />
+      <div className="flex flex-1 min-h-0 lg:overflow-hidden">
+        <div
+          className="flex-1 min-w-0 flex flex-col lg:overflow-hidden mx-auto px-4 lg:px-6"
+          style={{ maxWidth: 'var(--layout-max-width, none)' }}
+        >
+          <Header
             config={config}
             layout={layout}
-            isOpen={isSidebarOpen}
-            onClose={closeSidebar}
+            isSidebarOpen={isSidebarOpen}
+            onToggleSidebar={toggleSidebar}
           />
 
-          <main
-            id="main-content"
-            className="flex-1 flex flex-col lg:min-h-0 bg-[var(--color-bg-primary)] transition-colors overflow-x-hidden"
-          >
-            {children}
-          </main>
+          <TabsNav config={config} />
+
+          <div className="flex flex-1 lg:min-h-0">
+            <Sidebar
+              config={config}
+              layout={layout}
+              isOpen={isSidebarOpen}
+              onClose={closeSidebar}
+            />
+
+            <main
+              id="main-content"
+              className="flex-1 flex flex-col lg:min-h-0 bg-[var(--color-bg-primary)] transition-colors overflow-x-hidden"
+            >
+              {children}
+            </main>
+          </div>
         </div>
-      </div>
 
-      {isDesktop && <DesktopChatColumn />}
-      {chatOverlay}
+        {isDesktop && <DesktopChatColumn />}
+        {chatOverlay}
+      </div>
     </div>,
   );
 }

package/vendored/components/mdx/NativeSubscribeForm.tsx

@@ -1,7 +1,7 @@
 // builder/build-service/components/mdx/NativeSubscribeForm.tsx
 'use client';
 
-import { useEffect, useState, type CSSProperties, type FormEvent } from 'react';
+import { useEffect, useState, type CSSProperties, type FormEvent, type ReactNode } from 'react';
 
 export interface NativeSubscribeFormProps {
   provider: string; // 'resend'
@@ -13,10 +13,11 @@ export interface NativeSubscribeFormProps {
 }
 
 // Solid primary button (the collapsed trigger and the form's submit share it).
-// Kept compact — the iOS 16px-min rule is for inputs, not buttons.
+// Kept compact — the iOS 16px-min rule is for inputs, not buttons. Radius tracks
+// the theme's button token (--radius-md) so it matches the docs' own buttons.
 const PRIMARY_BUTTON: CSSProperties = {
   fontSize: '0.875rem', padding: '0.4rem 0.85rem', border: 0,
-  borderRadius: '0.375rem', cursor: 'pointer',
+  borderRadius: 'var(--radius-md, 0.375rem)', cursor: 'pointer',
   background: 'var(--color-primary, #2563eb)', color: '#fff',
 };
 
@@ -26,6 +27,24 @@ const LINK_BUTTON: CSSProperties = {
   cursor: 'pointer', textDecoration: 'underline', font: 'inherit',
 };
 
+// Themed card surface that gives the signup its own space. Built entirely from
+// theme tokens — the same vocabulary the docs' <Card> uses — so it tracks the
+// active theme: Nebula's sharp corners, Jam/Pulsar's flat (no-shadow) look, and
+// each theme's border weight and colors, with hardcoded fallbacks only for
+// contexts that ship no theme CSS. The secondary-bg surface sits a shade off the
+// page's primary background; the email field below stays primary-bg, so it pops
+// against the card (page → card → field layering, like the docs' code panels).
+const CARD: CSSProperties = {
+  background: 'var(--color-bg-secondary, #f9fafb)',
+  border: 'var(--border-width, 1px) solid var(--color-border, #e4e4e7)',
+  borderRadius: 'var(--radius-lg, 0.75rem)',
+  boxShadow: 'var(--shadow-sm, none)',
+  padding: '1.25rem',
+  // Tidy widget width: the form inside caps at 28rem, so a wider card would leave
+  // dead space on the right. Capping keeps it a contained box, not a full-bleed band.
+  maxWidth: '32rem',
+};
+
 /** Site-wide "this visitor already subscribed" flag. Per-origin (localStorage is
  *  already scoped to the published site), so one signup is remembered across
  *  every changelog page rather than re-nagging the same reader. */
@@ -58,6 +77,25 @@ function subscribeEndpoint(): string {
   return '/_jd/subscribe';
 }
 
+/** Base wrapper classes shared by every render state. `jd-emailsubscribe` (and
+ *  the `--card` / `--placeholder` modifiers) are stable, intentionally-unstyled
+ *  hooks for customer custom-CSS — no theme stylesheet targets them today. */
+const BASE_CLASS = 'jd-emailsubscribe not-prose my-6';
+
+/** Themed card wrapper around the active-form states (the expanded form and the
+ *  post-submit confirmation). Keeps the box stable through submit so the layout
+ *  never jumps mid-interaction. The compact `collapsed` trigger and the
+ *  returning-subscriber line render bare instead — they're meant to recede, not
+ *  occupy a full card. */
+function Shell({ className, role, children }: { className?: string; role?: string; children: ReactNode }) {
+  return (
+    <div className={`${BASE_CLASS} jd-emailsubscribe--card ${className ?? ''}`.trim()}
+      role={role} style={CARD}>
+      {children}
+    </div>
+  );
+}
+
 /**
  * On-brand, first-party signup form for native-capture providers (Resend). Posts
  * the email to Jamdesk's same-origin /_jd/subscribe; the customer's API key stays
@@ -107,14 +145,16 @@ export function NativeSubscribeForm({ provider, title, description, collapsed, c
     }
   }
 
-  const wrapperClass = `jd-emailsubscribe not-prose my-6 ${className ?? ''}`.trim();
+  const wrapperClass = `${BASE_CLASS} ${className ?? ''}`.trim();
+  // Shared title heading — rendered identically in the two card states (done + form).
+  const titleEl = title ? <p className="mb-1 font-semibold text-theme-text-primary">{title}</p> : null;
 
   if (status === 'done') {
     return (
-      <div className={wrapperClass} role="status">
-        {title && <p className="mb-1 font-semibold text-theme-text-primary">{title}</p>}
+      <Shell className={className} role="status">
+        {titleEl}
         <p className="text-sm text-theme-text-secondary">Thanks — you&rsquo;re subscribed.</p>
-      </div>
+      </Shell>
     );
   }
 
@@ -146,8 +186,8 @@ export function NativeSubscribeForm({ provider, title, description, collapsed, c
   }
 
   return (
-    <div className={wrapperClass}>
-      {title && <p className="mb-1 font-semibold text-theme-text-primary">{title}</p>}
+    <Shell className={className}>
+      {titleEl}
       {description && <p className="mb-3 text-sm text-theme-text-secondary">{description}</p>}
       <form onSubmit={onSubmit} style={{ display: 'flex', gap: '0.5rem', flexWrap: 'wrap', alignItems: 'center', maxWidth: '28rem' }}>
         {/* Honeypot: a deliberately odd name (NOT website/url/email, which password
@@ -155,11 +195,12 @@ export function NativeSubscribeForm({ provider, title, description, collapsed, c
             fill it; humans can't see it. Off-screen + aria-hidden + tabIndex -1. */}
         <input type="text" name="jd_hp" tabIndex={-1} autoComplete="off" aria-hidden="true"
           defaultValue="" style={{ position: 'absolute', left: '-5000px' }} />
-        {/* font-size:16px avoids iOS auto-zoom (monorepo UI rule). */}
+        {/* font-size:16px avoids iOS auto-zoom (monorepo UI rule). primary-bg field
+            pops against the card's secondary-bg surface; radius tracks the theme. */}
         <input type="email" name="email" required value={email}
           onChange={(e) => { setEmail(e.target.value); if (status === 'error') setStatus('idle'); }}
           disabled={status === 'submitting'} placeholder="you@example.com" aria-label="Email address"
-          style={{ flex: 1, minWidth: 0, fontSize: '16px', padding: '0.4rem 0.75rem', border: '1px solid var(--color-border, #d4d4d8)', borderRadius: '0.375rem', background: 'var(--color-bg-primary, #fff)', color: 'var(--color-text-primary, #18181b)' }} />
+          style={{ flex: 1, minWidth: 0, fontSize: '16px', padding: '0.4rem 0.75rem', border: 'var(--border-width, 1px) solid var(--color-border, #d4d4d8)', borderRadius: 'var(--radius-md, 0.375rem)', background: 'var(--color-bg-primary, #fff)', color: 'var(--color-text-primary, #18181b)' }} />
         <button type="submit" disabled={status === 'submitting'} style={PRIMARY_BUTTON}>
           {status === 'submitting' ? 'Subscribing…' : 'Subscribe'}
         </button>
@@ -167,6 +208,6 @@ export function NativeSubscribeForm({ provider, title, description, collapsed, c
       {status === 'error' && (
         <p className="mt-2 text-sm text-amber-700 dark:text-amber-400" role="alert">Something went wrong. Please try again.</p>
       )}
-    </div>
+    </Shell>
   );
 }

package/vendored/components/navigation/Header.tsx

@@ -275,9 +275,12 @@ export function Header({ config, layout = 'header-logo', tabsPosition: tabsPosit
   // Different header positioning based on layout
   // sidebar-logo: sticky (for Pulsar theme)
   // header-logo: sticky (for Jam, Nebula - supports max-width constraint)
+  // `top` is offset by the banner height on mobile (where the page scrolls) so
+  // the sticky header parks just below the banner. On desktop the header lives
+  // in an overflow-hidden column already below the banner, so reset to 0.
   const headerClasses = layout === 'sidebar-logo'
-    ? 'sticky top-0 z-40 bg-[var(--color-bg-content,var(--color-bg-primary))]/80 backdrop-blur-md border-b border-[var(--color-border)] transition-colors'
-    : 'sticky top-0 z-50 bg-[var(--color-bg-primary)]/80 backdrop-blur-md transition-colors';
+    ? 'sticky top-[var(--jd-banner-height,0px)] lg:top-0 z-40 bg-[var(--color-bg-content,var(--color-bg-primary))]/80 backdrop-blur-md border-b border-[var(--color-border)] transition-colors'
+    : 'sticky top-[var(--jd-banner-height,0px)] lg:top-0 z-50 bg-[var(--color-bg-primary)]/80 backdrop-blur-md transition-colors';
 
   return (
     <>

package/vendored/components/navigation/LastUpdated.tsx

@@ -0,0 +1,44 @@
+/**
+ * "Last updated on <date>" line shown at the bottom of a docs page when the
+ * project enables `metadata.timestamp` in docs.json.
+ *
+ * The date string is injected into page frontmatter at build time (the date of
+ * the last git commit that touched the file — see lib/git-last-modified.ts).
+ * Rendered server-side as an absolute date so the output is deterministic and
+ * stable inside the ISR cache (no relative "N days ago" drift, no client JS).
+ */
+
+// Format in UTC so the displayed day matches the stored day regardless of the
+// server's timezone. Built once at module load and reused across page renders.
+const DATE_FORMAT = new Intl.DateTimeFormat('en-US', {
+  year: 'numeric',
+  month: 'long',
+  day: 'numeric',
+  timeZone: 'UTC',
+});
+
+/** Format a stored YYYY-MM-DD (or ISO) date as e.g. "June 15, 2026". */
+export function formatLastUpdated(value: string): string | null {
+  // Date-only strings parse as UTC midnight, matching DATE_FORMAT's timeZone.
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return null;
+  return DATE_FORMAT.format(date);
+}
+
+interface LastUpdatedProps {
+  /** Stored date string (YYYY-MM-DD), or undefined when unavailable. */
+  date?: string;
+}
+
+export function LastUpdated({ date }: LastUpdatedProps) {
+  if (!date) return null;
+  const formatted = formatLastUpdated(date);
+  if (!formatted) return null;
+
+  return (
+    <p className="mt-8 text-sm text-[var(--color-text-muted)]">
+      Last updated on{' '}
+      <time dateTime={date}>{formatted}</time>
+    </p>
+  );
+}

package/vendored/components/navigation/Sidebar.tsx

@@ -694,7 +694,7 @@ export function Sidebar({ config, layout = 'header-logo', tabsPosition: tabsPosi
   const showTopDivider = resolvedNav.externalAnchors.length > 0;
   const hasTopTabsBar = getTabsFromConfig(config, pathname || undefined).length > 1 && !showTabsInSidebar;
   const desktopSidebarClasses = layout === 'sidebar-logo'
-    ? 'lg:fixed lg:top-0 lg:left-0 lg:bottom-0 lg:z-40'
+    ? 'lg:fixed lg:top-[var(--jd-banner-height,0px)] lg:left-0 lg:bottom-0 lg:z-40'
     : 'lg:sticky lg:self-start lg:z-30 lg:flex-shrink-0';
 
   return (

package/vendored/lib/banner-dismiss.ts

@@ -0,0 +1,53 @@
+// Banner dismissal persistence. The dismissal is keyed to a hash of the banner
+// content so that editing the message makes it reappear for everyone.
+// Modeled on lib/recent-searches.ts (SSR-safe localStorage access).
+
+const PREFIX = 'jamdesk_banner_dismissed_';
+
+export function bannerDismissKey(slug: string): string {
+  return `${PREFIX}${slug}`;
+}
+
+// Small deterministic djb2 hash → base36. Not cryptographic; only needs to
+// change when the content changes and stay stable otherwise.
+export function bannerHash(content: string): string {
+  let h = 5381;
+  for (let i = 0; i < content.length; i++) {
+    h = ((h << 5) + h + content.charCodeAt(i)) | 0;
+  }
+  return (h >>> 0).toString(36);
+}
+
+export function isBannerDismissed(slug: string, content: string): boolean {
+  if (typeof window === 'undefined') return false;
+  try {
+    return localStorage.getItem(bannerDismissKey(slug)) === bannerHash(content);
+  } catch {
+    return false;
+  }
+}
+
+export function dismissBanner(slug: string, content: string): void {
+  if (typeof window === 'undefined') return;
+  try {
+    localStorage.setItem(bannerDismissKey(slug), bannerHash(content));
+  } catch {
+    // Storage unavailable (private mode, quota) — fail open; banner just won't
+    // remember the dismissal.
+  }
+}
+
+/**
+ * Inline JS for the pre-paint <head> script. When the stored hash matches the
+ * current content it sets `data-jd-banner-dismissed` on <html>, so CSS can hide
+ * the bar before first paint (no flash for repeat visitors). slug + hash are
+ * JSON-encoded into the string for safety.
+ */
+export function bannerNoFlashScript(slug: string, content: string): string {
+  // Defense-in-depth: JSON.stringify escapes `<` in V8 but the spec does not
+  // require it, so escape it ourselves — a slug can never break out of the
+  // surrounding <script> tag.
+  const key = JSON.stringify(bannerDismissKey(slug)).replace(/</g, '\\u003c');
+  const hash = JSON.stringify(bannerHash(content)).replace(/</g, '\\u003c');
+  return `(function(){try{if(localStorage.getItem(${key})===${hash}){document.documentElement.setAttribute('data-jd-banner-dismissed','')}}catch(e){}})();`;
+}

package/vendored/lib/content-loader.ts

@@ -14,6 +14,7 @@ import fs from 'fs';
 import path from 'path';
 import { parseFrontmatterLenient } from './frontmatter-utils';
 import { getDocsConfig as getStaticDocsConfig, getContentDir } from './docs';
+import { getGitLastModified, injectLastUpdated } from './page-timestamps';
 import {
   getDocsConfig as getIsrDocsConfig,
   getMdxContent,
@@ -41,6 +42,9 @@ export interface ContentLoader {
  */
 class StaticContentLoader implements ContentLoader {
   private contentDir: string;
+  // Per-page git date cache (dev preview): avoids a git spawn on every re-render.
+  // null = looked up, no committed date (untracked/new file or non-git dir).
+  private dateCache = new Map<string, string | null>();
 
   constructor() {
     this.contentDir = getContentDir();
@@ -51,8 +55,19 @@ class StaticContentLoader implements ContentLoader {
   }
 
   async getContent(pagePath: string): Promise<string> {
-    const filePath = path.join(this.contentDir, pagePath) + '.mdx';
-    return fs.readFileSync(filePath, 'utf8');
+    const relPath = pagePath + '.mdx';
+    const content = fs.readFileSync(path.join(this.contentDir, relPath), 'utf8');
+
+    // Dev parity with the build: when metadata.timestamp is on, inject the
+    // page's last git-commit date so the renderer shows "Last updated on …".
+    if (!this.getConfig().metadata?.timestamp) return content;
+
+    let date = this.dateCache.get(pagePath);
+    if (date === undefined) {
+      date = getGitLastModified(this.contentDir, relPath);
+      this.dateCache.set(pagePath, date);
+    }
+    return date ? injectLastUpdated(content, date) : content;
   }
 
   async getAllPaths(): Promise<string[]> {