npm - jamdesk - Versions diffs - 1.1.141 → 1.1.143 - Mend

jamdesk 1.1.141 → 1.1.143

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (58) hide show

package/dist/commands/dev.d.ts.map +1 -1
package/dist/commands/dev.js +20 -0
package/dist/commands/dev.js.map +1 -1
package/dist/lib/deprecated-components.d.ts +1 -0
package/dist/lib/deprecated-components.d.ts.map +1 -1
package/dist/lib/deprecated-components.js +1 -0
package/dist/lib/deprecated-components.js.map +1 -1
package/package.json +1 -1
package/vendored/app/[[...slug]]/page.tsx +8 -1
package/vendored/app/api/subscribe/[project]/route.ts +154 -0
package/vendored/components/chat/ChatMessage.tsx +49 -15
package/vendored/components/layout/EmbedLinkInterceptor.tsx +2 -4
package/vendored/components/mdx/EmailSubscribe.tsx +167 -0
package/vendored/components/mdx/MDXComponents.tsx +3 -0
package/vendored/components/mdx/NativeSubscribeForm.tsx +172 -0
package/vendored/components/search/SearchModal.tsx +19 -1
package/vendored/lib/deprecated-components.ts +1 -0
package/vendored/lib/docs-types.ts +30 -0
package/vendored/lib/email-subscribe-autoplacement.ts +46 -0
package/vendored/lib/email-subscribe-providers.ts +120 -0
package/vendored/lib/firestore-helpers.ts +20 -0
package/vendored/lib/is-modified-click.ts +11 -0
package/vendored/lib/middleware-helpers.ts +25 -0
package/vendored/lib/newsletter/adapters/beehiiv.ts +23 -0
package/vendored/lib/newsletter/adapters/brevo.ts +31 -0
package/vendored/lib/newsletter/adapters/kit.ts +35 -0
package/vendored/lib/newsletter/adapters/loops.ts +22 -0
package/vendored/lib/newsletter/adapters/mailchimp.ts +52 -0
package/vendored/lib/newsletter/adapters/resend.ts +23 -0
package/vendored/lib/newsletter/adapters/sendgrid.ts +23 -0
package/vendored/lib/newsletter/descriptors.ts +84 -0
package/vendored/lib/newsletter/http.ts +19 -0
package/vendored/lib/newsletter/registry.ts +27 -0
package/vendored/lib/newsletter/types.ts +52 -0
package/vendored/lib/newsletter-display.ts +43 -0
package/vendored/lib/preprocess-mdx.ts +20 -12
package/vendored/lib/redis.ts +32 -0
package/vendored/lib/render-doc-page.tsx +81 -25
package/vendored/lib/scanner-blocklist.ts +26 -1
package/vendored/lib/seo.ts +13 -2
package/vendored/lib/sitemap-xsl.ts +121 -0
package/vendored/lib/static-file-route.ts +7 -2
package/vendored/lib/validate-content-images.ts +150 -0
package/vendored/schema/docs-schema.json +28 -0
package/vendored/shared/status-reporter.ts +1 -1
package/vendored/workspace-package-lock.json +87 -171
package/dist/__tests__/unit/dev-workspace-symlinks.test.d.ts +0 -2
package/dist/__tests__/unit/dev-workspace-symlinks.test.d.ts.map +0 -1
package/dist/__tests__/unit/dev-workspace-symlinks.test.js +0 -112
package/dist/__tests__/unit/dev-workspace-symlinks.test.js.map +0 -1
package/dist/__tests__/unit/language-filter.test.d.ts +0 -2
package/dist/__tests__/unit/language-filter.test.d.ts.map +0 -1
package/dist/__tests__/unit/language-filter.test.js +0 -166
package/dist/__tests__/unit/language-filter.test.js.map +0 -1
package/dist/lib/language-filter.d.ts +0 -31
package/dist/lib/language-filter.d.ts.map +0 -1
package/dist/lib/language-filter.js +0 -14
package/dist/lib/language-filter.js.map +0 -1

package/vendored/components/mdx/EmailSubscribe.tsx ADDED Viewed

@@ -0,0 +1,167 @@
+// builder/build-service/components/mdx/EmailSubscribe.tsx
+'use client';
+import { useEffect, useRef } from 'react';
+import {
+  resolveEmailSubscribeEmbed,
+  type EmailSubscribeProps,
+} from '@/lib/email-subscribe-providers';
+import { NativeSubscribeForm } from './NativeSubscribeForm';
+/**
+ * Re-create a <script> so the browser executes it. Scripts inserted via
+ * innerHTML never run; copying attributes + inline text onto a fresh
+ * createElement node and appending it does.
+ */
+export function reviveScript(original: HTMLScriptElement): HTMLScriptElement {
+  const s = document.createElement('script');
+  for (const attr of Array.from(original.attributes)) s.setAttribute(attr.name, attr.value);
+  s.text = original.text;
+  return s;
+}
+/**
+ * External vendor scripts (Kit/MailerLite `index.js`) load AT MOST ONCE per src,
+ * globally. Re-running one on App Router soft-navigation double-registers the
+ * widget (duplicate handlers, double analytics) — the spec's #1 risk. They are
+ * appended to <body> (not the mount) so they survive route changes and aren't
+ * removed on unmount.
+ *
+ * KNOWN LIMITATION: a script-based INLINE embed won't re-inject its form on
+ * back-navigation (the script won't re-run). For inline use prefer iframe/form
+ * embeds; for script-based providers (Kit/MailerLite) place the signup on a
+ * dedicated changelog page (full page load) — documented in the component docs.
+ */
+const loadedExternalScripts = new Set<string>();
+/** Test-only: clears the global load-once cache between cases. */
+export function _resetEmbedScriptCacheForTest(): void {
+  loadedExternalScripts.clear();
+}
+/**
+ * <EmailSubscribe> — inline newsletter / changelog-notification signup.
+ *
+ * Hosts any ESP's paste-able embed (raw `snippet`) or a `provider` shorthand
+ * (mailchimp/buttondown/substack/beehiiv). The embed is injected on the client
+ * so it previews in `jamdesk dev` and runs on published ISR. Positioned for
+ * INLINE embeds; for floating/popup/sticky widgets use site-wide Custom JS.
+ *
+ * The dashboard editor renders <EmailSubscribePlaceholder> instead (mapped in
+ * the editor's builder-bridge) so vendor scripts never execute in the dashboard
+ * origin.
+ */
+export function EmailSubscribe(props: EmailSubscribeProps) {
+  const { title, description, className, collapsed } = props;
+  const mountRef = useRef<HTMLDivElement | null>(null);
+  const embed = resolveEmailSubscribeEmbed(props);
+  const embedKey = embed.kind === 'snippet' ? embed.html : embed.kind;
+  useEffect(() => {
+    const mount = mountRef.current;
+    if (!mount) return;
+    // Defense-in-depth: NEVER execute a customer snippet inside the dashboard
+    // editor origin, even if the component-map placeholder override regresses.
+    // The editor's builder-bridge.ts sets this flag at module load (Task 9); it
+    // is never set on published sites or CLI dev, so injection proceeds there.
+    if (typeof window !== 'undefined' &&
+        (window as { __JD_EDITOR_PREVIEW__?: boolean }).__JD_EDITOR_PREVIEW__) {
+      return;
+    }
+    if (embed.kind !== 'snippet') {
+      mount.replaceChildren();
+      return;
+    }
+    // Idempotent: clear any prior injection (StrictMode double-invoke, remount,
+    // or snippet change) before injecting the current embed.
+    mount.replaceChildren();
+    const tpl = document.createElement('template');
+    tpl.innerHTML = embed.html;
+    for (const old of Array.from(tpl.content.querySelectorAll('script'))) {
+      const src = old.getAttribute('src');
+      if (src) {
+        // External script: load once, globally, on <body> — survives soft-nav.
+        old.remove();
+        if (!loadedExternalScripts.has(src)) {
+          loadedExternalScripts.add(src);
+          document.body.appendChild(reviveScript(old as HTMLScriptElement));
+        }
+      } else {
+        // Inline script (config like window.CONFIG=…): revive in place.
+        old.replaceWith(reviveScript(old as HTMLScriptElement));
+      }
+    }
+    mount.appendChild(tpl.content);
+    return () => mount.replaceChildren();
+    // embedKey is the only input that changes the injected DOM.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [embedKey]);
+  if (embed.kind === 'native') {
+    // First-party form posting to /_jd/subscribe — no snippet injection.
+    return <NativeSubscribeForm provider={embed.provider} title={title} description={description} collapsed={collapsed} className={className} />;
+  }
+  if (embed.kind !== 'snippet') {
+    if (process.env.NODE_ENV === 'production') {
+      // Fail safe: never show end users a "coming soon" / config-error string.
+      return <div ref={mountRef} className="jd-emailsubscribe-empty" />;
+    }
+    const msg =
+      embed.kind === 'native-pending'
+        ? `EmailSubscribe: "${embed.provider}" has no embeddable form yet (API-only). ` +
+          'Bridge it via a no-code form (Tally/Formspree → automation) for now — native support is planned.'
+        : `EmailSubscribe: ${embed.reason}.`;
+    return (
+      <div className="jd-emailsubscribe not-prose my-6 rounded-md border border-amber-300 bg-amber-50 p-3 text-sm text-amber-800 dark:border-amber-700 dark:bg-amber-900/20 dark:text-amber-300" role="note">
+        {msg}
+      </div>
+    );
+  }
+  return (
+    <div className={`jd-emailsubscribe not-prose my-6 ${className ?? ''}`.trim()}>
+      {title && <p className="mb-1 font-semibold text-theme-text-primary">{title}</p>}
+      {description && <p className="mb-3 text-sm text-theme-text-secondary">{description}</p>}
+      <div ref={mountRef} className="jd-emailsubscribe-mount" />
+    </div>
+  );
+}
+/**
+ * Editor-preview stand-in: static placeholder, never executes the embed. Swapped
+ * into the editor component map (builder-bridge.ts). Not used on published sites
+ * or in CLI dev.
+ */
+/** Placeholder label text per resolved embed kind. Early returns keep the
+ *  discriminated-union narrowing that makes `embed.provider` / `embed.reason`
+ *  accessible (avoids a nested ternary). */
+function placeholderLabel(embed: ReturnType<typeof resolveEmailSubscribeEmbed>, title?: string): string {
+  switch (embed.kind) {
+    case 'snippet':
+    case 'native':
+      return `${title || 'Email signup'} — live on your published site`;
+    case 'native-pending':
+      return `Email signup: "${embed.provider}" has no embeddable form — bridge it via a no-code form.`;
+    case 'none':
+      return `Email signup: not configured (${embed.reason}). Set a provider + id, or a snippet.`;
+  }
+}
+export function EmailSubscribePlaceholder(props: EmailSubscribeProps) {
+  // Resolve (cheaply, no injection) so the editor surfaces config errors instead
+  // of hiding them — a dashboard author would otherwise never see the dev notice
+  // (prod env) and could ship a permanently-empty signup.
+  const embed = resolveEmailSubscribeEmbed(props);
+  const ok = embed.kind === 'snippet' || embed.kind === 'native';
+  const label = placeholderLabel(embed, props.title);
+  const tone = ok
+    ? 'border-theme-border bg-theme-bg-secondary text-theme-text-secondary'
+    : 'border-amber-400 bg-amber-50 text-amber-800 dark:border-amber-700 dark:bg-amber-900/20 dark:text-amber-300';
+  return (
+    <div className={`jd-emailsubscribe jd-emailsubscribe--placeholder not-prose my-6 rounded-md border border-dashed p-4 text-sm ${tone}`} role="note">
+      <span aria-hidden="true">{ok ? '✉ ' : '⚠ '}</span>
+      {label}
+    </div>
+  );
+}

package/vendored/components/mdx/MDXComponents.tsx CHANGED Viewed

@@ -27,6 +27,7 @@ import { Icon } from './Icon';
 import { Expandable } from './Expandable';
 import { Frame } from './Frame';
 import { Update } from './Update';
+import { EmailSubscribe } from './EmailSubscribe';
 import { Tabs, Tab } from './Tabs';
 import { Table, Row, Cell } from './Table';
 import { CodePanel } from '../ui/CodePanel';
@@ -211,6 +212,8 @@ export const MDXComponents = {
   Frame,
   // Update for changelog entries
   Update,
+  // EmailSubscribe — inline newsletter / changelog-notification signup
+  EmailSubscribe,
   // Tabs for organizing content
   Tabs,
   Tab,

package/vendored/components/mdx/NativeSubscribeForm.tsx ADDED Viewed

@@ -0,0 +1,172 @@
+// builder/build-service/components/mdx/NativeSubscribeForm.tsx
+'use client';
+import { useEffect, useState, type CSSProperties, type FormEvent } from 'react';
+export interface NativeSubscribeFormProps {
+  provider: string; // 'resend'
+  title?: string;
+  description?: string;
+  /** Start collapsed: a compact button that expands to the form on click. */
+  collapsed?: boolean;
+  className?: string;
+}
+// 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.
+const PRIMARY_BUTTON: CSSProperties = {
+  fontSize: '0.875rem', padding: '0.4rem 0.85rem', border: 0,
+  borderRadius: '0.375rem', cursor: 'pointer',
+  background: 'var(--color-primary, #2563eb)', color: '#fff',
+};
+// Inline text button for the "use a different email" escape hatch.
+const LINK_BUTTON: CSSProperties = {
+  background: 'none', border: 0, padding: 0, color: 'var(--color-primary, #2563eb)',
+  cursor: 'pointer', textDecoration: 'underline', font: 'inherit',
+};
+/** 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. */
+const SUBSCRIBED_KEY = 'jd_subscribed';
+function readSubscribed(): boolean {
+  try {
+    return typeof window !== 'undefined' &&
+      window.localStorage.getItem(SUBSCRIBED_KEY) === '1';
+  } catch {
+    // Private-mode / storage-disabled: fail open (show the form).
+    return false;
+  }
+}
+function rememberSubscribed(): void {
+  try {
+    window.localStorage.setItem(SUBSCRIBED_KEY, '1');
+  } catch {
+    // Best-effort — a storage failure just means we re-show next visit.
+  }
+}
+/** Same-origin endpoint. Hosted-at-/docs sites serve the signup under /docs,
+ *  mirroring useChat's `/docs/_chat` swap (builder/cli/vendored/hooks/useChat.ts). */
+function subscribeEndpoint(): string {
+  if (typeof window !== 'undefined' && window.location.pathname.startsWith('/docs')) {
+    return '/docs/_jd/subscribe';
+  }
+  return '/_jd/subscribe';
+}
+/**
+ * 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
+ * server-side. No third-party script — safe to render anywhere the live component
+ * renders (published ISR + CLI dev; the editor uses the placeholder).
+ *
+ * Two display refinements, native-only (we control this DOM, unlike vendor
+ * embeds):
+ *   - `collapsed`: render a compact button that expands to the form on click.
+ *   - Already-subscribed memory: once a visitor subscribes, every later mount
+ *     shows a one-line "you're subscribed" with a "use a different email" escape
+ *     hatch instead of the full form. The flag is read AFTER mount (useEffect)
+ *     so SSR/first-paint stays deterministic and hydration never mismatches.
+ */
+export function NativeSubscribeForm({ provider, title, description, collapsed, className }: NativeSubscribeFormProps) {
+  const [email, setEmail] = useState('');
+  const [status, setStatus] = useState<'idle' | 'submitting' | 'done' | 'error'>('idle');
+  // Set after mount only — keeps the server/first-client render deterministic.
+  const [remembered, setRemembered] = useState(false);
+  // The visitor explicitly opened the form (collapsed trigger or "different email").
+  const [forceOpen, setForceOpen] = useState(false);
+  useEffect(() => {
+    if (readSubscribed()) setRemembered(true);
+  }, []);
+  async function onSubmit(e: FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    if (status === 'submitting') return;
+    const jd_hp = (e.currentTarget.elements.namedItem('jd_hp') as HTMLInputElement | null)?.value ?? '';
+    setStatus('submitting');
+    try {
+      const res = await fetch(subscribeEndpoint(), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, jd_hp, provider }),
+      });
+      if (res.ok) {
+        rememberSubscribed();
+        setRemembered(true);
+        setStatus('done');
+      } else {
+        setStatus('error');
+      }
+    } catch {
+      setStatus('error');
+    }
+  }
+  const wrapperClass = `jd-emailsubscribe not-prose my-6 ${className ?? ''}`.trim();
+  if (status === 'done') {
+    return (
+      <div className={wrapperClass} role="status">
+        {title && <p className="mb-1 font-semibold text-theme-text-primary">{title}</p>}
+        <p className="text-sm text-theme-text-secondary">Thanks — you&rsquo;re subscribed.</p>
+      </div>
+    );
+  }
+  // Already-subscribed wins over the collapsed trigger: a returning subscriber
+  // sees the status line, not a generic "Subscribe" button.
+  if (remembered && !forceOpen) {
+    return (
+      <div className={wrapperClass}>
+        <p className="text-sm text-theme-text-secondary">
+          You&rsquo;re subscribed to the newsletter.{' '}
+          <button type="button" onClick={() => { setEmail(''); setStatus('idle'); setForceOpen(true); }}
+            style={LINK_BUTTON}>
+            Use a different email?
+          </button>
+        </p>
+      </div>
+    );
+  }
+  // Collapsed: a compact button standing in for the whole form until clicked.
+  if (collapsed && !forceOpen) {
+    return (
+      <div className={wrapperClass}>
+        <button type="button" onClick={() => setForceOpen(true)} style={PRIMARY_BUTTON}>
+          {title || 'Subscribe to updates'}
+        </button>
+      </div>
+    );
+  }
+  return (
+    <div className={wrapperClass}>
+      {title && <p className="mb-1 font-semibold text-theme-text-primary">{title}</p>}
+      {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
+            managers autofill — a filled honeypot silently drops a real user). Bots
+            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). */}
+        <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)' }} />
+        <button type="submit" disabled={status === 'submitting'} style={PRIMARY_BUTTON}>
+          {status === 'submitting' ? 'Subscribing…' : 'Subscribe'}
+        </button>
+      </form>
+      {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>
+  );
+}

package/vendored/components/search/SearchModal.tsx CHANGED Viewed

@@ -157,6 +157,7 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
   const router = useRouter();
   const resultsContainerRef = useRef<HTMLDivElement>(null);
   const modalRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
   // Track if user clicked a result (to avoid double-tracking on modal close)
   const hasTrackedRef = useRef(false);
   // Store last search state for tracking on modal close
@@ -519,17 +520,34 @@ export function SearchModal({ isOpen, onClose, popularPages, onNavigate }: Searc
           <div className="flex items-center gap-3 px-4 py-3 border-b border-[var(--color-border)]">
             <i className="fa-solid fa-magnifying-glass h-4 w-4 text-[var(--color-text-muted)] flex-shrink-0" aria-hidden="true" />
             <input
+              ref={inputRef}
               type="search"
               placeholder="Search documentation…"
               value={query}
               onChange={(e) => setQuery(e.target.value)}
-              className="flex-1 bg-transparent text-[var(--color-text-primary)] placeholder-[var(--color-text-muted)] outline-none text-base"
+              className="flex-1 bg-transparent text-[var(--color-text-primary)] placeholder-[var(--color-text-muted)] outline-none text-base [&::-webkit-search-cancel-button]:appearance-none [&::-webkit-search-decoration]:appearance-none"
               autoComplete="off"
               autoFocus
               aria-label="Search documentation"
               aria-controls="search-results"
               aria-activedescendant={rows[selectedIndex] ? `search-result-${selectedIndex}` : undefined}
             />
+            {query && (
+              <button
+                type="button"
+                onClick={() => {
+                  setQuery('');
+                  inputRef.current?.focus();
+                }}
+                className="flex items-center justify-center w-4 h-4 cursor-pointer rounded-full bg-[var(--color-text-muted)] hover:bg-[var(--color-text-secondary)] transition-colors flex-shrink-0 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-accent)]"
+                aria-label="Clear search"
+              >
+                <i
+                  className="fa-solid fa-xmark text-[9px] leading-none text-[var(--color-bg-primary)]"
+                  aria-hidden="true"
+                />
+              </button>
+            )}
             <button
               onClick={onClose}
               className="p-1.5 cursor-pointer hover:bg-[var(--color-bg-tertiary)] rounded-lg transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-accent)]"

package/vendored/lib/deprecated-components.ts CHANGED Viewed

@@ -24,6 +24,7 @@ export interface DeprecatedComponentInfo {
 /**
  * Map of deprecated components to their replacements.
  * Add new deprecated components here as they are removed.
+ * NEVER remove entries: render-time auto-migrate (preprocess-mdx.ts) rewrites stale R2 content with them forever.
  */
 export const DEPRECATED_COMPONENTS: Record<string, DeprecatedComponentInfo> = {
   CardGroup: {

package/vendored/lib/docs-types.ts CHANGED Viewed

@@ -614,6 +614,35 @@ export interface StylingConfig {
 // INTEGRATIONS
 // =============================================================================
+/**
+ * Customer-facing newsletter / changelog-notification signup (rendered by
+ * <EmailSubscribe>). Fields mirror EmailSubscribeProps (see
+ * lib/email-subscribe-providers.ts); `placement` opts into auto-rendering on
+ * changelog (`rss: true`) pages.
+ *
+ * NOTE: distinct from the dashboard's internal `addUserToResendNewsletter`
+ * (Jamdesk's own signup list) — this is per docs-project config.
+ */
+export interface NewsletterConfig {
+  /** Shorthand provider: mailchimp | buttondown | substack | beehiiv (v1). */
+  provider?: string;
+  /** Mailchimp: full form POST action URL. */
+  action?: string;
+  /** Buttondown / Substack: account username. */
+  username?: string;
+  /** Beehiiv: full iframe embed src URL. */
+  src?: string;
+  /** Raw embed snippet (any vendor) — escape hatch. */
+  snippet?: string;
+  /** iframe height in px for iframe providers (substack/beehiiv). */
+  height?: number;
+  /** Optional heading shown above the embed. */
+  title?: string;
+  description?: string;
+  /** 'changelog' auto-mounts on `rss: true` pages; 'none' (default) = manual. */
+  placement?: 'none' | 'changelog';
+}
 /**
  * Analytics and integration configurations (stubs - TODO: implement)
  */
@@ -629,6 +658,7 @@ export interface IntegrationsConfig {
   hightouch?: { writeKey: string; apiHost?: string };
   hotjar?: { hjid: string; hjsv: string };
   crisp?: { websiteId: string };
+  newsletter?: NewsletterConfig;
   intercom?: { appId: string };
   koala?: { publicApiKey: string };
   logrocket?: { appId: string };

package/vendored/lib/email-subscribe-autoplacement.ts ADDED Viewed

@@ -0,0 +1,46 @@
+// builder/build-service/lib/email-subscribe-autoplacement.ts
+import type { EmailSubscribeProps } from './email-subscribe-providers';
+/** Structural shape of the slice of config this resolver reads. Declared locally
+ *  so Task 2 type-checks on its own, WITHOUT waiting for Task 5 to add
+ *  `IntegrationsConfig.newsletter` — the real `DocsConfig` is structurally
+ *  assignable to this, so render-doc-page (Task 6) can pass its full config. */
+type NewsletterLike = EmailSubscribeProps & { placement?: 'none' | 'changelog' };
+/**
+ * Decide whether a changelog (`rss: true`) page should auto-render the
+ * configured signup. Returns the EmailSubscribe props (placement stripped) when
+ * `integrations.newsletter.placement === 'changelog'`, else null. Pure — so the
+ * gating is unit-tested without rendering the whole page.
+ */
+export function resolveAutoNewsletter(
+  rss: boolean | undefined,
+  config: { integrations?: { newsletter?: NewsletterLike } },
+  pageNewsletter?: boolean,
+): EmailSubscribeProps | null {
+  // Per-page escape hatch: frontmatter `newsletter: false` suppresses the
+  // configured auto-placement on THIS page (e.g. a non-changelog page that
+  // happens to set rss:true, or a localized changelog placing its own translated
+  // <EmailSubscribe>). Only an explicit `false` opts out.
+  if (pageNewsletter === false) return null;
+  const n = config.integrations?.newsletter;
+  if (!rss || !n || n.placement !== 'changelog') return null;
+  const { placement: _placement, ...props } = n;
+  void _placement;
+  return props;
+}
+/** True when the page's raw MDX already hand-places an `<EmailSubscribe>` tag.
+ *  Used to suppress auto-placement so an explicit author form isn't doubled.
+ *
+ *  Code is stripped first — fenced blocks (```…```) then inline spans (`…`) — so
+ *  a page that merely *documents* the component (a changelog entry or guide
+ *  showing `<EmailSubscribe />` in an example) isn't mistaken for a hand-placed
+ *  form and wrongly suppress its own `placement: changelog` auto-mount.
+ *  The trailing char class avoids matching `<EmailSubscribeFoo`. */
+export function mdxHasEmailSubscribe(rawContent: string): boolean {
+  const withoutCode = rawContent
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/`[^`\n]+`/g, '');
+  return /<EmailSubscribe[\s/>]/.test(withoutCode);
+}

package/vendored/lib/email-subscribe-providers.ts ADDED Viewed

@@ -0,0 +1,120 @@
+// builder/build-service/lib/email-subscribe-providers.ts
+import { NATIVE_PROVIDER_IDS } from './newsletter/descriptors';
+/**
+ * Props accepted by <EmailSubscribe> and (minus styling-only fields) by the
+ * docs.json `integrations.newsletter` block. All optional — the resolver
+ * decides what's renderable.
+ */
+export interface EmailSubscribeProps {
+  /** Shorthand provider key (case-insensitive). */
+  provider?: string;
+  /** Mailchimp: full form POST `action` URL. */
+  action?: string;
+  /** Buttondown / Substack: account username. */
+  username?: string;
+  /** Beehiiv: full iframe embed `src` URL. */
+  src?: string;
+  /** Raw embed snippet (any vendor) — escape hatch, takes priority. */
+  snippet?: string;
+  /** iframe height in px for iframe providers (substack/beehiiv). */
+  height?: number;
+  /** Optional on-brand heading above the embed. */
+  title?: string;
+  description?: string;
+  /** Start collapsed: render a compact "Subscribe" button that expands to the
+   *  full form on click (native providers only — embeds can't be controlled). */
+  collapsed?: boolean;
+  /** Extra class on the wrapper. */
+  className?: string;
+}
+export type ResolvedEmbed =
+  | { kind: 'snippet'; html: string }
+  | { kind: 'native'; provider: string }          // Phase 2: real form + capture endpoint
+  | { kind: 'native-pending'; provider: string }  // API-only, no native path yet
+  | { kind: 'none'; reason: string };
+/** API-only ESPs with no native path yet — friendly notice, never an error. */
+const NATIVE_PENDING_PROVIDERS = new Set(['mailersend']);
+/** Escape a user value before interpolating into an HTML attribute so a stray
+ *  quote/angle-bracket can't break out of the attribute or inject a tag.
+ *  Escapes single quotes too, so it stays safe even if an attribute is later
+ *  switched to single-quoted. */
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+const EMAIL_INPUT =
+  '<input type="email" name="EMAIL" required placeholder="you@example.com" ' +
+  'aria-label="Email address" ' +
+  'style="flex:1;min-width:0;font-size:16px;padding:0.5rem 0.75rem;border:1px solid var(--color-border, #d4d4d8);border-radius:0.375rem;background:var(--color-bg-primary, #fff);color:var(--color-text-primary, #18181b)" />';
+const SUBMIT_BUTTON =
+  '<button type="submit" ' +
+  'style="font-size:16px;padding:0.5rem 1rem;border:0;border-radius:0.375rem;cursor:pointer;background:var(--color-primary, #2563eb);color:#fff">Subscribe</button>';
+function formShell(action: string, emailName: string, target: string): string {
+  // `font-size:16px` on the input avoids iOS auto-zoom (monorepo UI rule).
+  // escapeAttr defends the field name even though callers pass literals today —
+  // a future provider deriving emailName from config can't inject an attribute.
+  const input = EMAIL_INPUT.replace('name="EMAIL"', `name="${escapeAttr(emailName)}"`);
+  return (
+    `<form action="${action}" method="post" target="${target}" ` +
+    `style="display:flex;gap:0.5rem;flex-wrap:wrap;align-items:center;max-width:28rem">` +
+    input +
+    SUBMIT_BUTTON +
+    `</form>`
+  );
+}
+function iframe(src: string, height: number): string {
+  // Height is provider-defaulted + author-overridable (`height` prop): a single
+  // magic number clips Substack's taller widget or pads Beehiiv's compact one.
+  return (
+    `<iframe src="${src}" width="100%" height="${height}" frameborder="0" scrolling="no" ` +
+    `title="Subscribe" style="border:0;background:transparent;max-width:28rem"></iframe>`
+  );
+}
+/** Provider shorthands whose markup is fully reconstructable from documented,
+ *  stable inputs. Mailchimp and beehiiv were here pre-native; they are now
+ *  handled by the NATIVE_PROVIDER_IDS branch above. */
+const PROVIDER_BUILDERS: Record<string, (p: EmailSubscribeProps) => ResolvedEmbed> = {
+  buttondown(p) {
+    if (!p.username) return { kind: 'none', reason: 'buttondown requires a "username"' };
+    const action = `https://buttondown.com/api/emails/embed-subscribe/${encodeURIComponent(p.username)}`;
+    return { kind: 'snippet', html: formShell(escapeAttr(action), 'email', 'popupwindow') };
+  },
+  substack(p) {
+    if (!p.username) return { kind: 'none', reason: 'substack requires a "username"' };
+    const sub = encodeURIComponent(p.username);
+    return { kind: 'snippet', html: iframe(escapeAttr(`https://${sub}.substack.com/embed`), p.height ?? 320) };
+  },
+};
+/** Turn EmailSubscribe props into a renderable embed decision. Pure. */
+export function resolveEmailSubscribeEmbed(p: EmailSubscribeProps): ResolvedEmbed {
+  if (p.snippet && p.snippet.trim()) return { kind: 'snippet', html: p.snippet };
+  const provider = p.provider?.trim().toLowerCase();
+  if (!provider) return { kind: 'none', reason: 'no provider or snippet specified' };
+  // Migration note: sites whose docs.json still says provider:"mailchimp"/"beehiiv"
+  // now resolve to a native form. With no dashboard creds the submission returns the
+  // uniform 404 and the form shows a neutral message. Owners must configure the
+  // provider in the dashboard (agreed native-replaces-embed migration).
+  if (NATIVE_PROVIDER_IDS.has(provider)) return { kind: 'native', provider };
+  if (NATIVE_PENDING_PROVIDERS.has(provider)) return { kind: 'native-pending', provider };
+  const builder = PROVIDER_BUILDERS[provider];
+  if (!builder) {
+    return { kind: 'none', reason: `provider "${provider}" has no shorthand — paste its embed via the "snippet" prop` };
+  }
+  return builder(p);
+}

package/vendored/lib/firestore-helpers.ts ADDED Viewed

@@ -0,0 +1,20 @@
+import admin from 'firebase-admin';
+/**
+ * True when a Firestore project claims this slug (the canonical slug lives at
+ * projects/{id}/github/config.slug — collection-group query avoids enumerating
+ * every project). Used as the server-side guard for expectOrphan deletes:
+ * orphan-purge tooling must never be able to wipe a live tenant, regardless of
+ * what a client-side script computed. The collection-group single-field index
+ * exemption for `github.slug` (COLLECTION_GROUP ASCENDING) already exists in
+ * dashboard/firestore.indexes.json, so this query needs no new index.
+ */
+export async function isSlugActive(slug: string): Promise<boolean> {
+  const snap = await admin
+    .firestore()
+    .collectionGroup('github')
+    .where('slug', '==', slug)
+    .limit(1)
+    .get();
+  return !snap.empty;
+}

package/vendored/lib/is-modified-click.ts ADDED Viewed

@@ -0,0 +1,11 @@
+import type { MouseEvent } from 'react';
+/**
+ * True when the user has asked the browser for special handling — new tab
+ * (cmd/ctrl), new window (shift), background tab (middle/non-primary button) —
+ * or another handler already claimed the event. Click interceptors must defer
+ * to native behavior in these cases instead of hijacking the click.
+ */
+export function isModifiedClick(e: MouseEvent): boolean {
+  return e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey;
+}