jamdesk 1.1.146 → 1.1.148

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.146",
+  "version": "1.1.148",
   "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/ConsentGate.tsx

@@ -0,0 +1,87 @@
+// builder/build-service/components/ConsentGate.tsx
+'use client';
+
+import { useEffect, useRef } from 'react';
+import type { GatedScript } from '../lib/consent-gating';
+
+const POLL_MS = 1000;
+
+function hasConsent(key: string, value: string): boolean {
+  try {
+    return window.localStorage.getItem(key) === value;
+  } catch {
+    // Storage unavailable (private mode / blocked iframe) → treat as no consent
+    return false;
+  }
+}
+
+function injectScripts(scripts: GatedScript[]): void {
+  for (const s of scripts) {
+    const el = document.createElement('script');
+    el.setAttribute('data-jd-consent-script', s.id);
+    if (s.kind === 'src' && s.src) {
+      el.src = s.src;
+      for (const [name, val] of Object.entries(s.attrs ?? {})) el.setAttribute(name, val);
+    } else if (s.kind === 'inline' && s.code) {
+      el.textContent = s.code;
+    } else {
+      continue;
+    }
+    (s.appendTo === 'head' ? document.head : document.body).appendChild(el);
+  }
+}
+
+/**
+ * Consent gate for analytics/tracking scripts (integrations.cookies).
+ * Renders nothing. Injects the given scripts once localStorage[consentKey]
+ * equals consentValue — immediately on mount if consent pre-exists, else via
+ * a storage listener (cross-tab) + poll (same-tab CMP writes don't fire
+ * storage events). Scripts are injected at most once per page load; consent
+ * revocation takes effect on the next page load.
+ */
+export function ConsentGate({
+  consentKey,
+  consentValue,
+  scripts,
+}: {
+  consentKey: string;
+  consentValue: string;
+  scripts: GatedScript[];
+}) {
+  // scripts is a fresh array identity each render (built server-side, serialized
+  // across the RSC boundary). Hold it in a ref so the effect doesn't list it as
+  // a dependency — otherwise a parent re-render before consent arrives would
+  // tear down and restart the polling window. Content is stable per page.
+  const scriptsRef = useRef(scripts);
+  scriptsRef.current = scripts;
+
+  useEffect(() => {
+    if ((window as any).__jdConsentInjected) return;
+    let intervalId: ReturnType<typeof setInterval> | undefined;
+
+    const stop = () => {
+      if (intervalId !== undefined) clearInterval(intervalId);
+      window.removeEventListener('storage', check);
+    };
+    const check = () => {
+      if ((window as any).__jdConsentInjected) { stop(); return; }
+      if (!hasConsent(consentKey, consentValue)) return;
+      (window as any).__jdConsentInjected = true;
+      stop();
+      injectScripts(scriptsRef.current);
+    };
+
+    check();
+    if (!(window as any).__jdConsentInjected) {
+      // Diagnostics: wrong key/value otherwise fails silently forever.
+      console.debug(
+        `[Jamdesk] Consent gating active — analytics withheld until localStorage["${consentKey}"] equals the configured value.`,
+      );
+      window.addEventListener('storage', check);
+      intervalId = setInterval(check, POLL_MS);
+    }
+    return stop;
+  }, [consentKey, consentValue]);
+
+  return null;
+}

package/vendored/components/mdx/NativeSubscribeForm.tsx

@@ -12,11 +12,21 @@ export interface NativeSubscribeFormProps {
   className?: string;
 }
 
+// Shared control height for the email field + Subscribe button so they line up
+// exactly. The input must carry 16px text (iOS no-zoom rule) which otherwise
+// makes it taller than the smaller-font button; pinning both to one height with
+// border-box collapses the mismatch. 2rem (32px) stays compact yet clears the
+// WCAG 24px minimum target.
+const CONTROL_HEIGHT = '2rem';
+
 // 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. Radius tracks
 // the theme's button token (--radius-md) so it matches the docs' own buttons.
+// inline-flex centers the label inside the fixed CONTROL_HEIGHT box.
 const PRIMARY_BUTTON: CSSProperties = {
-  fontSize: '0.8125rem', padding: '0.35rem 0.75rem', border: 0,
+  display: 'inline-flex', alignItems: 'center', justifyContent: 'center',
+  height: CONTROL_HEIGHT, boxSizing: 'border-box',
+  fontSize: '0.8125rem', padding: '0 0.85rem', border: 0,
   borderRadius: 'var(--radius-md, 0.375rem)', cursor: 'pointer',
   background: 'var(--color-primary, #2563eb)', color: '#fff',
 };
@@ -189,6 +199,11 @@ export function NativeSubscribeForm({ provider, title, description, collapsed, c
     <Shell className={className}>
       {titleEl}
       {description && <p className="mb-3 text-sm text-theme-text-secondary">{description}</p>}
+      {/* The field keeps 16px text (iOS no-zoom), but the placeholder reads a
+          touch smaller — inline styles can't reach ::placeholder, so scope it by
+          the stable jd-emailsubscribe hook. Smaller ::placeholder font doesn't
+          re-trigger iOS zoom (that keys off the input's own font-size). */}
+      <style>{`.jd-emailsubscribe input[type="email"]::placeholder{font-size:0.875rem}`}</style>
       <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
             managers autofill — a filled honeypot silently drops a real user). Bots
@@ -196,11 +211,12 @@ export function NativeSubscribeForm({ provider, title, description, collapsed, c
         <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). primary-bg field
-            pops against the card's secondary-bg surface; radius tracks the theme. */}
+            pops against the card's secondary-bg surface; radius tracks the theme.
+            height+border-box matches the Subscribe button exactly. */}
         <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.35rem 0.7rem', 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)' }} />
+          disabled={status === 'submitting'} placeholder="you@email.com" aria-label="Email address"
+          style={{ flex: 1, minWidth: 0, height: CONTROL_HEIGHT, boxSizing: 'border-box', fontSize: '16px', padding: '0 0.7rem', 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>

package/vendored/lib/consent-gating.ts

@@ -0,0 +1,119 @@
+// builder/build-service/lib/consent-gating.ts
+// Consent gating for analytics/tracking scripts (integrations.cookies) and
+// CMP loader validation (integrations.osano / integrations.termly).
+// Pure module — no DOM, no React — so the server layout and tests share it.
+import type { IntegrationsConfig } from './docs-types';
+
+export interface GatedScript {
+  /** Stable id — used as DOM marker (data-jd-consent-script) and React key */
+  id: string;
+  kind: 'inline' | 'src';
+  /** Inline JS source (kind: 'inline') */
+  code?: string;
+  /** External src (kind: 'src') */
+  src?: string;
+  /** Extra attributes set via setAttribute (kind: 'src'); '' = boolean attr */
+  attrs?: Record<string, string>;
+  appendTo: 'head' | 'body';
+}
+
+// Tracking-ID guards: these values get interpolated into inline JS / URLs, so
+// they must be strictly validated (same posture as the existing Crisp guard).
+// /i is intentional: tolerate lowercase-typed IDs (alphanumerics + hyphen
+// can't break out of the inline JS string regardless of case).
+const GA4_ID_RE = /^G-[A-Z0-9]+$/i;
+const GTM_ID_RE = /^GTM-[A-Z0-9]+$/i;
+const CRISP_ID_RE = /^[a-f0-9-]{36}$/; // mirrors layout-helpers.tsx guard
+
+// CMP loader URL pins. Defense-in-depth: schema validates these too, but the
+// renderer must not trust config blobs from R2. Path charset includes '.' so
+// every schema-valid Osano URL also passes here (schema only pins prefix/suffix).
+const OSANO_SRC_RE = /^https:\/\/cmp\.osano\.com\/[A-Za-z0-9._/-]+\/osano\.js$/;
+const TERMLY_SRC_RE =
+  /^https:\/\/app\.termly\.io\/resource-blocker\/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(\?autoBlock=(on|off))?$/;
+
+export function isConsentGatingEnabled(integrations: IntegrationsConfig | undefined): boolean {
+  const c = integrations?.cookies;
+  return typeof c?.key === 'string' && c.key.length > 0 &&
+         typeof c?.value === 'string' && c.value.length > 0;
+}
+
+/** Validated CMP script srcs to render ungated in <head> (Osano first). */
+export function getCmpScriptSrcs(integrations: IntegrationsConfig | undefined): string[] {
+  const srcs: string[] = [];
+  const osano = integrations?.osano?.scriptSource;
+  if (osano && OSANO_SRC_RE.test(osano)) srcs.push(osano);
+  const termly = integrations?.termly?.scriptSource;
+  if (termly && TERMLY_SRC_RE.test(termly)) srcs.push(termly);
+  return srcs;
+}
+
+/**
+ * Build serializable descriptors for every analytics/tracking script.
+ * Emitted unconditionally — the caller is responsible for the prod gate:
+ * layout-helpers renders <ConsentGate> (and thus calls this) only when
+ * NODE_ENV === 'production', matching the dev-suppression the direct render
+ * paths already apply to Plausible/Crisp/customJs/first-party analytics.
+ */
+export function buildGatedScripts({
+  integrations,
+  customJs,
+  analyticsScript,
+}: {
+  integrations: IntegrationsConfig | undefined;
+  customJs: string | null;
+  analyticsScript: string | null;
+}): GatedScript[] {
+  const scripts: GatedScript[] = [];
+  const i = integrations ?? {};
+
+  if (i.plausible?.scriptUrl) {
+    // Proxy mode — mirrors PlausibleScript's scriptUrl branch in layout-helpers
+    scripts.push({ id: 'plausible-proxy', kind: 'src', src: i.plausible.scriptUrl, attrs: { async: '' }, appendTo: 'head' });
+    scripts.push({
+      id: 'plausible-proxy-init', kind: 'inline', appendTo: 'head',
+      code: 'window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};plausible.init()',
+    });
+  } else if (i.plausible?.domain) {
+    const baseServer = (i.plausible.server || 'https://plausible.io').replace(/\/+$/, '');
+    const attrs: Record<string, string> = { defer: '', 'data-domain': i.plausible.domain };
+    if (i.plausible.server) attrs['data-api'] = `${baseServer}/api/event`;
+    scripts.push({ id: 'plausible', kind: 'src', src: `${baseServer}/js/script.js`, attrs, appendTo: 'head' });
+  }
+
+  // GTM/GA4 here are raw inline equivalents of the standard snippets. The
+  // ungated direct renders use @next/third-parties (ConditionalGTM/ConditionalGA)
+  // instead; these descriptors deliberately bypass it because they're injected
+  // client-side at consent time, not at SSR. Functionally equivalent for tracking,
+  // but they carry NO Next.js CSP nonce and GTM omits the <noscript> iframe
+  // fallback (irrelevant — no-JS clients can't trigger the consent gate anyway).
+  if (i.gtm?.tagId && GTM_ID_RE.test(i.gtm.tagId)) {
+    scripts.push({
+      id: 'gtm', kind: 'inline', appendTo: 'head',
+      code: `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer','${i.gtm.tagId}');`,
+    });
+  }
+
+  if (i.ga4?.measurementId && GA4_ID_RE.test(i.ga4.measurementId)) {
+    scripts.push({
+      id: 'ga4-loader', kind: 'src', appendTo: 'head', attrs: { async: '' },
+      src: `https://www.googletagmanager.com/gtag/js?id=${i.ga4.measurementId}`,
+    });
+    scripts.push({
+      id: 'ga4-init', kind: 'inline', appendTo: 'head',
+      code: `window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}gtag('js',new Date());gtag('config','${i.ga4.measurementId}');`,
+    });
+  }
+
+  if (i.crisp?.websiteId && CRISP_ID_RE.test(i.crisp.websiteId)) {
+    scripts.push({
+      id: 'crisp', kind: 'inline', appendTo: 'body',
+      code: `window.$crisp=[];window.CRISP_WEBSITE_ID="${i.crisp.websiteId}";(function(){var d=document;var s=d.createElement("script");s.src="https://client.crisp.chat/l.js";s.async=1;d.getElementsByTagName("head")[0].appendChild(s)})();`,
+    });
+  }
+
+  if (customJs) scripts.push({ id: 'custom-js', kind: 'inline', code: customJs, appendTo: 'body' });
+  if (analyticsScript) scripts.push({ id: 'jd-analytics', kind: 'inline', code: analyticsScript, appendTo: 'body' });
+
+  return scripts;
+}

package/vendored/lib/docs-types.ts

@@ -644,7 +644,10 @@ export interface NewsletterConfig {
 }
 
 /**
- * Analytics and integration configurations (stubs - TODO: implement)
+ * Analytics and integration configurations.
+ * Implemented: ga4, gtm, plausible, crisp, osano, termly, cookies (consent
+ * gating), analytics opt-out via AnalyticsConfig. Others remain config-only
+ * stubs accepted for Mintlify compatibility.
  */
 export interface IntegrationsConfig {
   ga4?: { measurementId: string };
@@ -664,6 +667,7 @@ export interface IntegrationsConfig {
   logrocket?: { appId: string };
   mixpanel?: { projectToken: string };
   osano?: { scriptSource: string };
+  termly?: { scriptSource: string };
   pirsch?: { id: string };
   posthog?: { apiKey: string; apiHost?: string };
   plausible?: { domain?: string; server?: string; scriptUrl?: string };

package/vendored/lib/layout-helpers.tsx

@@ -25,6 +25,8 @@ import type { BackgroundConfig, DocsConfig, FontConfig, LanguageCode } from '@/l
 import { LinkPrefixProvider } from '@/lib/link-prefix-context';
 import { ProjectSlugProvider } from '@/lib/project-slug-context';
 import { getAnalyticsScript } from '@/lib/analytics-script';
+import { isConsentGatingEnabled, buildGatedScripts, getCmpScriptSrcs } from '@/lib/consent-gating';
+import { ConsentGate } from '@/components/ConsentGate';
 import { AgentDirective } from './agent-directive';
 import { fetchCustomCss, fetchCustomJs } from '@/lib/r2-content';
 import { toHreflang } from '@/lib/language-utils';
@@ -429,6 +431,21 @@ export async function DocsChrome({
     ? getAnalyticsScript(resolvedProjectSlug)
     : null;
 
+  // integrations.cookies consent gating: when key+value are configured, all
+  // analytics/tracking scripts are withheld until the CMP writes
+  // localStorage[key] === value (ConsentGate injects them client-side).
+  const consentGating = isConsentGatingEnabled(config.integrations);
+  // CMP loaders (Osano/Termly) are NEVER gated — they ARE the consent banner.
+  const cmpScriptSrcs = process.env.NODE_ENV === 'production'
+    ? getCmpScriptSrcs(config.integrations)
+    : [];
+  // Preconnect origins are best-effort: getCmpScriptSrcs only returns
+  // regex-validated absolute https URLs (so new URL can't throw today), but
+  // guard anyway — a malformed preconnect must never 500 the whole render.
+  const cmpPreconnectOrigins = cmpScriptSrcs
+    .map((src) => { try { return new URL(src).origin; } catch { return null; } })
+    .filter((origin): origin is string => origin !== null);
+
   // Global banner: only emit the pre-paint no-flash guard for a dismissible
   // banner (a non-dismissible banner is never hidden, so the guard would risk
   // hiding a mandatory message via a stale dismissal hash). Trimmed content
@@ -457,6 +474,15 @@ export async function DocsChrome({
   return (
     <html lang={toHreflang(lang)} dir={dir} suppressHydrationWarning data-scroll-behavior="smooth" data-scroll-locked="true">
       <head>
+        {/* CMP scripts must be first + synchronous: auto-blocking CMPs
+            (Osano/Termly) need to intercept later scripts. Never gated.
+            preconnect first: the sync fetch is render-blocking. */}
+        {cmpPreconnectOrigins.map((origin) => (
+          <link key={`pc-${origin}`} rel="preconnect" href={origin} />
+        ))}
+        {cmpScriptSrcs.map((src) => (
+          <script key={src} src={src} />
+        ))}
         {/*
           SSR scroll lock — prevents Chrome's same-tab cross-origin "preserve
           scroll" heuristic from scrolling #content-scroll-container on first
@@ -674,7 +700,7 @@ export async function DocsChrome({
             {customCss}
           </style>
         )}
-        {process.env.NODE_ENV === 'production' && (config.integrations?.plausible?.domain || config.integrations?.plausible?.scriptUrl) && (
+        {!consentGating && process.env.NODE_ENV === 'production' && (config.integrations?.plausible?.domain || config.integrations?.plausible?.scriptUrl) && (
           <PlausibleScript
             domain={config.integrations.plausible.domain}
             server={config.integrations.plausible.server}
@@ -684,7 +710,7 @@ export async function DocsChrome({
       </head>
       <body className={fontClassName} data-theme={themeName || 'jam'} data-decoration={decoration || undefined} suppressHydrationWarning>
         {!embed && <AgentDirective hostAtDocs={!!config.hostAtDocs} />}
-        {config.integrations?.gtm?.tagId && (
+        {!consentGating && config.integrations?.gtm?.tagId && (
           <ConditionalGTM gtmId={config.integrations.gtm.tagId} />
         )}
         <ThemeProvider
@@ -712,7 +738,7 @@ export async function DocsChrome({
           client" warning in `jamdesk dev`. Same pattern as the
           project-subdomain hydration suppressor in <head>.
         */}
-        {process.env.NODE_ENV === 'production' && config.integrations?.crisp?.websiteId &&
+        {!consentGating && process.env.NODE_ENV === 'production' && config.integrations?.crisp?.websiteId &&
           /^[a-f0-9-]{36}$/.test(config.integrations.crisp.websiteId) && (
           <script
             dangerouslySetInnerHTML={{
@@ -720,15 +746,26 @@ export async function DocsChrome({
             }}
           />
         )}
-        {process.env.NODE_ENV === 'production' && customJs && (
+        {!consentGating && process.env.NODE_ENV === 'production' && customJs && (
           <script dangerouslySetInnerHTML={{ __html: customJs }} />
         )}
-        {process.env.NODE_ENV === 'production' && analyticsScript && (
+        {!consentGating && process.env.NODE_ENV === 'production' && analyticsScript && (
           <script dangerouslySetInnerHTML={{ __html: analyticsScript }} />
         )}
-        {config.integrations?.ga4?.measurementId && (
+        {!consentGating && config.integrations?.ga4?.measurementId && (
           <ConditionalGA gaId={config.integrations.ga4.measurementId} />
         )}
+        {consentGating && process.env.NODE_ENV === 'production' && (
+          <ConsentGate
+            consentKey={config.integrations!.cookies!.key!}
+            consentValue={config.integrations!.cookies!.value!}
+            scripts={buildGatedScripts({
+              integrations: config.integrations,
+              customJs,
+              analyticsScript,
+            })}
+          />
+        )}
         <JdReadySentinel />
       </body>
     </html>

package/vendored/lib/validate-config.ts

@@ -36,6 +36,9 @@ export interface IntegrationsConfig {
   ga4?: { measurementId: string };
   gtm?: { tagId: string };
   plausible?: { domain?: string; server?: string; scriptUrl?: string };
+  osano?: { scriptSource: string };
+  termly?: { scriptSource: string };
+  cookies?: { key?: string; value?: string };
   [key: string]: unknown;
 }
 

package/vendored/schema/docs-schema.json

@@ -1258,6 +1258,19 @@
                             ],
                             "additionalProperties": false
                         },
+                        "termly": {
+                            "type": "object",
+                            "properties": {
+                                "scriptSource": {
+                                    "type": "string",
+                                    "pattern": "^https://app\\.termly\\.io/resource-blocker/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(\\?autoBlock=(on|off))?$"
+                                }
+                            },
+                            "required": [
+                                "scriptSource"
+                            ],
+                            "additionalProperties": false
+                        },
                         "pirsch": {
                             "type": "object",
                             "properties": {
@@ -1345,12 +1358,18 @@
                             "type": "object",
                             "properties": {
                                 "key": {
-                                    "type": "string"
+                                    "type": "string",
+                                    "minLength": 1
                                 },
                                 "value": {
-                                    "type": "string"
+                                    "type": "string",
+                                    "minLength": 1
                                 }
                             },
+                            "required": [
+                                "key",
+                                "value"
+                            ],
                             "additionalProperties": false
                         }
                     },

package/vendored/workspace-package-lock.json

@@ -2939,9 +2939,9 @@
       "license": "MIT"
     },
     "node_modules/electron-to-chromium": {
-      "version": "1.5.373",
-      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.373.tgz",
-      "integrity": "sha512-G2Hym8JIf/QreuseqkDibgH8Ci8KfJzqGDKdakbhSx9UltwRBH2cBLAWU/lBX0sCdv0TlhyxQyDCnSfxgMWsjA==",
+      "version": "1.5.374",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.374.tgz",
+      "integrity": "sha512-HCF5i7izveksHSGqa7mhDh6tr3Uz9Dar2RAjwuh69bw3QGPVObjQIgLwQWeO/Rxp9/r0KdboKy9RbpQDl97fjg==",
       "license": "ISC"
     },
     "node_modules/enhanced-resolve": {