@eventcatalog/core 5.0.0-beta.8 → 5.0.0

package/eventcatalog/src/components/SideNav/NestedSideBar/index.tsx

@@ -21,57 +21,56 @@ import {
   type FavoriteItem,
 } from '@stores/favorites-store';
 import {
+  buildNodeLookup,
   canCollapseGroup,
   findNodeKeyByUrl,
   getBadgeClasses,
   getDefaultCollapsedState,
   hidesDefaultItemIcon,
   isGroupCollapsed,
+  resolveNavRef,
+  rootLevel,
+  stripBasePath,
   toggleGroupCollapsed,
+  type NavigationLevel,
+  type SidebarSnapshot,
 } from './utils';
 import { resolveIconUrl } from '@utils/icon';
 
 const cn = (...classes: (string | false | undefined)[]) => classes.filter(Boolean).join(' ');
 
-/**
- * Strip the configured base path from a pathname so URL pattern matching works
- * regardless of the base path setting (e.g. `/eventcatalog/docs/...` → `/docs/...`).
- */
-const stripBasePath = (pathname: string): string => {
-  const base = __EC_BASE__.replace(/\/$/, ''); // e.g. '/eventcatalog'
-  if (base && pathname.startsWith(base)) {
-    return pathname.slice(base.length) || '/';
-  }
-  return pathname;
-};
-
 // ============================================
 // Component
 // ============================================
 
-type NavigationLevel = {
-  key: string | null; // The key of the node that was drilled into (null for root)
-  entries: ChildRef[];
-  title: string;
-  badge?: string; // Category badge (e.g., "Domain", "Service")
+type NestedSideBarProps = {
+  /**
+   * This page's level, built on the server. It renders the sidebar into the HTML and keeps
+   * the island showing it until the full navigation data (sidebar-data.json) is loaded.
+   */
+  snapshot?: SidebarSnapshot;
 };
 
-export default function NestedSideBar() {
-  const data = useStore(sidebarStore);
+export default function NestedSideBar({ snapshot }: NestedSideBarProps) {
+  const storeData = useStore(sidebarStore);
   const favorites = useStore(favoritesStore);
+  // Drill-down, restoring state and favorites need the whole catalog; until it loads the
+  // snapshot only shows this page's level
+  const hasFullData = storeData !== null;
+  const data = storeData ?? snapshot?.data ?? null;
 
   // Guard against undefined data (e.g., during hydration)
   // Use useMemo to ensure stable references for roots and nodes
   const roots = useMemo(() => data?.roots ?? [], [data?.roots]);
   const nodes = useMemo(() => data?.nodes ?? {}, [data?.nodes]);
 
-  const [navigationStack, setNavigationStack] = useState<NavigationLevel[]>(() => [
-    { key: null, entries: [], title: 'Documentation' },
-  ]);
+  const [navigationStack, setNavigationStack] = useState<NavigationLevel[]>(
+    () => snapshot?.stack ?? [{ key: null, entries: [], title: 'Documentation' }]
+  );
   const [animationKey, setAnimationKey] = useState(0);
   const [slideDirection, setSlideDirection] = useState<'forward' | 'backward' | null>(null);
   const [isInitialized, setIsInitialized] = useState(false);
-  const [currentPath, setCurrentPath] = useState<string>('');
+  const [currentPath, setCurrentPath] = useState<string>(snapshot?.url ?? '');
   const [sectionCollapsePreferences, setSectionCollapsePreferences] = useState(loadCollapsedSections);
   const [showPathPreview, setShowPathPreview] = useState(false);
   const [showFullPath, setShowFullPath] = useState(false);
@@ -79,33 +78,7 @@ export default function NestedSideBar() {
 
   // Build a lookup map for faster URL navigation
   // Map format: "type:id" -> "nodeKey"
-  const nodeLookup = useMemo(() => {
-    const lookup = new Map<string, string>();
-
-    Object.entries(nodes).forEach(([key, value]) => {
-      // Skip keys that are references (string values pointing to other keys)
-      // These are unversioned aliases like "domain:E-Commerce" -> "domain:E-Commerce:1.0.0"
-      if (typeof value === 'string') return;
-
-      // Key formats:
-      // - "type:id:version" (e.g., "service:OrdersService:0.0.3")
-      // - "type:id" (e.g., "user:john", "team:backend") - non-versioned resources
-      // - "list:name" (e.g., "list:domains") - skip these
-      const parts = key.split(':');
-
-      // Skip list items
-      if (parts[0] === 'list') return;
-
-      if (parts.length >= 2) {
-        // Store as "type:id"
-        const type = parts[0];
-        const id = parts[1];
-        lookup.set(`${type}:${id}`, key);
-      }
-    });
-
-    return lookup;
-  }, [nodes]);
+  const nodeLookup = useMemo(() => buildNodeLookup(nodes), [nodes]);
 
   /**
    * Toggle section collapse state
@@ -126,7 +99,7 @@ export default function NestedSideBar() {
       setNavigationStack((prevStack) => {
         // Only update if the current stack has no entries (initial state)
         if (prevStack.length === 1 && prevStack[0].entries.length === 0) {
-          return [{ key: null, entries: roots, title: 'Documentation' }];
+          return [rootLevel(roots)];
         }
         return prevStack;
       });
@@ -146,21 +119,7 @@ export default function NestedSideBar() {
    * Resolve a child reference to a NavNode
    * Handles both direct keys and string references (unversioned aliases pointing to versioned keys)
    */
-  const resolveRef = useCallback(
-    (ref: ChildRef): NavNode | null => {
-      if (typeof ref === 'string') {
-        const node = nodes[ref];
-        if (!node) return null;
-        // If node is a string, it's a reference to another key (e.g., unversioned alias)
-        if (typeof node === 'string') {
-          return (nodes[node] as NavNode) ?? null;
-        }
-        return node;
-      }
-      return ref;
-    },
-    [nodes]
-  );
+  const resolveRef = useCallback((ref: ChildRef): NavNode | null => resolveNavRef(nodes, ref), [nodes]);
 
   /**
    * Check if a node is visible (default: true)
@@ -175,7 +134,7 @@ export default function NestedSideBar() {
    */
   const buildStackFromPath = useCallback(
     (path: string[]): NavigationLevel[] => {
-      const stack: NavigationLevel[] = [{ key: null, entries: roots, title: 'Documentation' }];
+      const stack: NavigationLevel[] = [rootLevel(roots)];
 
       for (const key of path) {
         const node = resolveRef(key);
@@ -281,7 +240,7 @@ export default function NestedSideBar() {
           if (foundNode && foundNode.pages && foundNode.pages.length > 0) {
             // Fallback: Flattened navigation
             return [
-              { key: null, entries: roots, title: 'Documentation' },
+              rootLevel(roots),
               { key: foundNodeKey, entries: foundNode.pages, title: foundNode.title, badge: foundNode.badge },
             ];
           }
@@ -296,7 +255,7 @@ export default function NestedSideBar() {
             setSlideDirection('backward');
             setAnimationKey((prev) => prev + 1);
           }
-          return [{ key: null, entries: roots, title: 'Documentation' }];
+          return [rootLevel(roots)];
         });
         return true;
       }
@@ -309,14 +268,14 @@ export default function NestedSideBar() {
    * Restore state from localStorage on mount, or navigate to URL
    */
   useEffect(() => {
-    if (!data || roots.length === 0 || isInitialized) return;
+    if (!hasFullData || roots.length === 0 || isInitialized) return;
 
     const currentUrl = window.location.pathname;
     const normalizedCurrentUrl = stripBasePath(currentUrl);
 
     // Force root navigation on homepage
     if (normalizedCurrentUrl === '/' || normalizedCurrentUrl === '') {
-      setNavigationStack([{ key: null, entries: roots, title: 'Documentation' }]);
+      setNavigationStack([rootLevel(roots)]);
       setIsInitialized(true);
       return;
     }
@@ -347,7 +306,7 @@ export default function NestedSideBar() {
       const targetNode = resolveRef(targetKey);
       if (targetNode && targetNode.pages && targetNode.pages.length > 0) {
         finalStack = [
-          { key: null, entries: roots, title: 'Documentation' },
+          rootLevel(roots),
           { key: targetKey, entries: targetNode.pages, title: targetNode.title, badge: targetNode.badge },
         ];
       }
@@ -355,13 +314,13 @@ export default function NestedSideBar() {
 
     // 3. Fallback to root
     if (!finalStack) {
-      setNavigationStack([{ key: null, entries: roots, title: 'Documentation' }]);
+      setNavigationStack([rootLevel(roots)]);
     } else {
       setNavigationStack(finalStack);
     }
 
     setIsInitialized(true);
-  }, [data, roots, isInitialized, buildStackFromPath, findNodeKeyForUrl, tryConnectStack, resolveRef]);
+  }, [hasFullData, roots, isInitialized, buildStackFromPath, findNodeKeyForUrl, tryConnectStack, resolveRef]);
 
   /**
    * Save state whenever navigation changes
@@ -575,6 +534,7 @@ export default function NestedSideBar() {
    * Handle drilling down into an item with children
    */
   const handleDrillDown = (node: NavNode, nodeKey: string | null) => {
+    if (!hasFullData) return;
     if (node.pages && node.pages.length > 0) {
       setSlideDirection('forward');
       setAnimationKey((prev) => prev + 1);
@@ -590,7 +550,7 @@ export default function NestedSideBar() {
    * Navigate back one level
    */
   const navigateBack = () => {
-    if (navigationStack.length > 1) {
+    if (hasFullData && navigationStack.length > 1) {
       setSlideDirection('backward');
       setAnimationKey((prev) => prev + 1);
       setNavigationStack(navigationStack.slice(0, -1));
@@ -604,7 +564,7 @@ export default function NestedSideBar() {
    * Navigate to a specific level in the stack
    */
   const navigateToLevel = (levelIndex: number) => {
-    if (levelIndex < navigationStack.length - 1) {
+    if (hasFullData && levelIndex < navigationStack.length - 1) {
       setSlideDirection('backward');
       setAnimationKey((prev) => prev + 1);
       setNavigationStack(navigationStack.slice(0, levelIndex + 1));
@@ -634,6 +594,7 @@ export default function NestedSideBar() {
    * Navigate to a favorited item
    */
   const navigateToFavorite = (favorite: FavoriteItem) => {
+    if (!hasFullData) return;
     // If it has an href and no children, just navigate to the URL
     const node = resolveRef(favorite.nodeKey);
     if (favorite.href && (!node?.pages || node.pages.length === 0)) {

package/eventcatalog/src/components/SideNav/NestedSideBar/storage.ts

@@ -107,6 +107,8 @@ export const saveCollapsedSections = (preferences: SectionCollapsePreferences):
 };
 
 export const loadCollapsedSections = (): SectionCollapsePreferences => {
+  // Rendered on the server for the first paint, where there is nothing saved yet
+  if (typeof localStorage === 'undefined') return createSectionCollapsePreferences();
   try {
     const stored = localStorage.getItem(SECTION_PREFERENCES_KEY);
     if (stored) {

package/eventcatalog/src/components/SideNav/NestedSideBar/utils.ts

@@ -1,9 +1,130 @@
 // Shared utilities for NestedSideBar components
 
-import type { NavNode } from '@stores/sidebar-store/state';
+import type { ChildRef, NavigationData, NavNode } from '@stores/sidebar-store/state';
 
 export const SIDEBAR_GROUP_COLLAPSE_THRESHOLD = 5;
 
+/**
+ * Strip the configured base path from a pathname so URL pattern matching works
+ * regardless of the base path setting (e.g. `/eventcatalog/docs/...` → `/docs/...`).
+ */
+export const stripBasePath = (pathname: string): string => {
+  const base = __EC_BASE__.replace(/\/$/, ''); // e.g. '/eventcatalog'
+  if (base && pathname.startsWith(base)) {
+    return pathname.slice(base.length) || '/';
+  }
+  return pathname;
+};
+
+export type NavigationLevel = {
+  key: string | null; // The key of the node that was drilled into (null for root)
+  entries: ChildRef[];
+  title: string;
+  badge?: string; // Category badge (e.g., "Domain", "Service")
+};
+
+export const rootLevel = (roots: ChildRef[]): NavigationLevel => ({ key: null, entries: roots, title: 'Documentation' });
+
+/** Resolve a child reference to a node, following unversioned aliases (string → key). */
+export const resolveNavRef = (nodes: NavigationData['nodes'], ref: ChildRef): NavNode | null => {
+  if (typeof ref !== 'string') return ref;
+  const node = nodes[ref];
+  if (!node) return null;
+  if (typeof node === 'string') return (nodes[node] as NavNode) ?? null;
+  return node;
+};
+
+/** Map of "type:id" → versioned node key, used to match URLs to nodes. */
+export const buildNodeLookup = (nodes: NavigationData['nodes']): Map<string, string> => {
+  const lookup = new Map<string, string>();
+
+  Object.entries(nodes).forEach(([key, value]) => {
+    // Skip keys that are references (string values pointing to other keys)
+    // These are unversioned aliases like "domain:E-Commerce" -> "domain:E-Commerce:1.0.0"
+    if (typeof value === 'string') return;
+
+    // Key formats:
+    // - "type:id:version" (e.g., "service:OrdersService:0.0.3")
+    // - "type:id" (e.g., "user:john", "team:backend") - non-versioned resources
+    // - "list:name" (e.g., "list:domains") - skip these
+    const parts = key.split(':');
+
+    // Skip list items
+    if (parts[0] === 'list') return;
+
+    if (parts.length >= 2) {
+      // Store as "type:id"
+      lookup.set(`${parts[0]}:${parts[1]}`, key);
+    }
+  });
+
+  return lookup;
+};
+
+/**
+ * What the sidebar shows for a URL before it knows the reader's saved drill-down path:
+ * the root level on the homepage or for pages without children, otherwise the matching
+ * resource's own level (the same "flattened" stack the client falls back to).
+ */
+export const getStackForUrl = (
+  url: string,
+  data: NavigationData,
+  nodeLookup: ReadonlyMap<string, string> = buildNodeLookup(data.nodes)
+): NavigationLevel[] => {
+  const root = rootLevel(data.roots);
+  if (url === '/' || url === '') return [root];
+
+  const targetKey = findNodeKeyByUrl(url, data.nodes, nodeLookup);
+  const target = targetKey ? resolveNavRef(data.nodes, targetKey) : null;
+  if (!targetKey || !target?.pages?.length) return [root];
+
+  return [root, { key: targetKey, entries: target.pages, title: target.title, badge: target.badge }];
+};
+
+/**
+ * Everything the sidebar needs to render one page's level, without the whole catalog: the
+ * stack for the URL and only the nodes that level shows (its items, and the contents of its
+ * groups). Rendered on the server so the sidebar appears with the HTML, and handed to the
+ * island so it keeps showing it until the full navigation data loads.
+ */
+export type SidebarSnapshot = {
+  url: string;
+  stack: NavigationLevel[];
+  data: NavigationData;
+};
+
+const nodeLookupCache = new WeakMap<NavigationData, Map<string, string>>();
+
+export const buildSidebarSnapshot = (data: NavigationData, url: string): SidebarSnapshot => {
+  let nodeLookup = nodeLookupCache.get(data);
+  if (!nodeLookup) {
+    nodeLookup = buildNodeLookup(data.nodes);
+    nodeLookupCache.set(data, nodeLookup);
+  }
+
+  const stack = getStackForUrl(url, data, nodeLookup);
+  const level = stack[stack.length - 1];
+  const nodes: NavigationData['nodes'] = {};
+
+  const include = (ref: ChildRef) => {
+    if (typeof ref === 'string') {
+      if (ref in nodes) return;
+      const value = data.nodes[ref];
+      if (value === undefined) return;
+      nodes[ref] = value;
+      if (typeof value === 'string' && data.nodes[value] !== undefined) nodes[value] = data.nodes[value];
+    }
+    const node = resolveNavRef(data.nodes, ref);
+    // Groups render their children inline; items with children only need their own node
+    if (node?.type === 'group') node.pages?.forEach(include);
+  };
+
+  if (level.key) include(level.key);
+  level.entries.forEach(include);
+
+  return { url, stack, data: { roots: data.roots, nodes } };
+};
+
 /**
  * The user's overrides of each group's default collapse state, keyed by group id.
  * A group is in at most one set; absence means "use the group's default".

package/eventcatalog/src/components/SideNav/SideNav.astro

@@ -3,10 +3,18 @@ import type { HTMLAttributes } from 'astro/types';
 
 interface Props extends Omit<HTMLAttributes<'div'>, 'children'> {}
 import NestedSideBar from './NestedSideBar';
+import { buildSidebarSnapshot, stripBasePath } from './NestedSideBar/utils';
+import { getNestedSideBarData } from '@stores/sidebar-store/state';
 import { ClientRouter } from 'astro:transitions';
+
+// Render this page's sidebar level into the HTML so it shows before any JavaScript runs;
+// the full navigation still loads from /api/sidebar-data.json (see SearchDataLoader)
+const snapshot = buildSidebarSnapshot(await getNestedSideBarData(), stripBasePath(Astro.url.pathname));
 ---
 
 <div {...Astro.props}>
   <ClientRouter />
-  <NestedSideBar client:only="react" />
+  <NestedSideBar client:only="react" snapshot={snapshot}>
+    <NestedSideBar slot="fallback" snapshot={snapshot} />
+  </NestedSideBar>
 </div>

package/eventcatalog/src/components/TrialBadge.astro

@@ -1,7 +1,7 @@
 ---
 import catalog from '@utils/eventcatalog-config/catalog';
 import { isDevMode } from '@utils/feature';
-import { getLicenseDaysLeft, getTrialStatus, LICENSE_FAQ_URL, TRIAL_LENGTH_DAYS } from '@utils/trial';
+import { BUY_BUSINESS_URL, getLicenseDaysLeft, getTrialStatus, TRIAL_LENGTH_DAYS } from '@utils/trial';
 import { getLicenseStatus } from '@utils/license';
 import { buildUrl } from '@utils/url-builder';
 
@@ -29,20 +29,17 @@ const title = licenseExpired
   : licenseDaysLeft !== undefined
     ? `Your EventCatalog commercial license expires on ${licensedUntil?.toLocaleDateString()}. Renew it to keep using EventCatalog commercially.`
     : trial?.ended
-      ? `Your ${TRIAL_LENGTH_DAYS}-day EventCatalog trial ended on ${trial.endsAt.toLocaleDateString()}. Learn about licensing.`
-      : `You're on a ${TRIAL_LENGTH_DAYS}-day EventCatalog trial, ending on ${trial?.endsAt.toLocaleDateString()}. Learn about licensing.`;
+      ? `Your ${TRIAL_LENGTH_DAYS}-day EventCatalog trial ended on ${trial.endsAt.toLocaleDateString()}. See your license settings.`
+      : `You're on a ${TRIAL_LENGTH_DAYS}-day EventCatalog trial, ending on ${trial?.endsAt.toLocaleDateString()}. See your license settings.`;
 const warning = licenseExpired || licenseDaysLeft !== undefined || trial?.ended;
-// An expiring or expired license opens the license settings (where it's renewed), the trial the license FAQ
-const isLicense = licenseExpired || licenseDaysLeft !== undefined;
-const href = isLicense ? buildUrl('/settings/license') : LICENSE_FAQ_URL;
+// The badge opens Settings > License, where the license is renewed or bought
+const href = buildUrl('/settings/license');
 ---
 
 {
   (licenseExpired || licenseDaysLeft !== undefined || trial) && (
     <a
       href={href}
-      target={isLicense ? undefined : '_blank'}
-      rel={isLicense ? undefined : 'noopener noreferrer'}
       title={title}
       data-trial-ended={trial?.ended ? 'true' : undefined}
       data-license-expired={licenseExpired ? 'true' : undefined}
@@ -50,7 +47,7 @@ const href = isLicense ? buildUrl('/settings/license') : LICENSE_FAQ_URL;
         'inline-flex items-center gap-1.5 whitespace-nowrap rounded-full border px-2.5 py-1 text-xs font-medium transition-colors',
         warning
           ? 'border-[rgb(var(--ec-badge-color-amber-text)/0.3)] bg-[rgb(var(--ec-badge-color-amber-background))] text-[rgb(var(--ec-badge-color-amber-text))] hover:opacity-90'
-          : 'border-[rgb(var(--ec-accent)/0.3)] bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent))] hover:bg-[rgb(var(--ec-accent)/0.15)]',
+          : 'border-transparent bg-[rgb(var(--ec-page-text))] text-[rgb(var(--ec-page-bg))] hover:opacity-85',
       ]}
     >
       <svg
@@ -80,3 +77,17 @@ const href = isLicense ? buildUrl('/settings/license') : LICENSE_FAQ_URL;
     </a>
   )
 }
+{
+  /* Once the trial has ended, a link to buy the Business plan sits next to the badge */
+  trial?.ended && (
+    <a
+      href={BUY_BUSINESS_URL}
+      target="_blank"
+      rel="noopener noreferrer"
+      data-buy-business="true"
+      class="inline-flex items-center whitespace-nowrap rounded-full border border-transparent bg-[rgb(var(--ec-page-text))] px-2.5 py-1 text-xs font-medium text-[rgb(var(--ec-page-bg))] transition-opacity hover:opacity-85"
+    >
+      Buy Business
+    </a>
+  )
+}

package/eventcatalog/src/content.config.ts

@@ -502,7 +502,24 @@ const agents = defineCollection({
   ),
 });
 
-const adrStatus = z.enum(ADR_STATUS_VALUES);
+// ADRs need a status and a date, and say so when they're missing or invalid. Astro's own message for
+// a missing or unreadable date was "Expected type date, received object", with the field name garbled.
+const adrStatus = z.enum(ADR_STATUS_VALUES, {
+  error: (issue) =>
+    issue.input === undefined ? `Required: one of ${ADR_STATUS_VALUES.map((value) => `"${value}"`).join(', ')}` : undefined,
+});
+const adrDate = z.preprocess(
+  // Converted to a date only when it's set: a missing date coerced first became an invalid date
+  (value) => (value == null ? value : new Date(value as string | number | Date)),
+  z.date({
+    error: (issue) =>
+      issue.input === undefined
+        ? 'Required: a date, e.g. 2026-06-01'
+        : issue.input instanceof Date
+          ? 'Invalid date: use a date, e.g. 2026-06-01'
+          : undefined,
+  })
+);
 
 const adrPointer = z.object({
   id: z.string(),
@@ -539,7 +556,7 @@ const adrs = defineCollection({
     z
       .object({
         status: adrStatus,
-        date: z.coerce.date(),
+        date: adrDate,
         decisionMakers: z.array(ownerReference).optional(),
         appliesTo: z.array(adrResourcePointer).optional(),
         supersedes: z.array(adrPointer).optional(),

package/eventcatalog/src/features/auth/error.astro

@@ -1,5 +1,6 @@
 ---
 import '../../styles/tailwind.css';
+import { formatPageTitle } from '@utils/page-title';
 // src/pages/auth/error.astro
 
 const { searchParams } = new URL(Astro.request.url);
@@ -14,6 +15,7 @@ const errorMessages = {
 
 // @ts-ignore
 const errorMessage = errorMessages[error] || errorMessages.Default;
+const pageTitle = formatPageTitle('Authentication Error');
 ---
 
 <!doctype html>
@@ -25,10 +27,10 @@ const errorMessage = errorMessages[error] || errorMessages.Default;
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
     <meta name="generator" content={Astro.generator} />
-    <title>Authentication Error - EventCatalog</title>
+    <title>{pageTitle}</title>
   </head>
   <body>
-    <main title="Authentication Error - EventCatalog">
+    <main title={pageTitle}>
       <div class="min-h-screen flex items-center justify-center bg-gray-50 py-12 px-4 sm:px-6 lg:px-8">
         <div class="max-w-md w-full space-y-8 text-center">
           <div>

package/eventcatalog/src/features/auth/login.astro

@@ -1,6 +1,7 @@
 ---
 import '../../styles/tailwind.css';
 import config from '@config';
+import { formatPageTitle } from '@utils/page-title';
 const { title, logo } = config;
 import { join } from 'node:path';
 import { isAuthEnabled, isSSR } from '@utils/feature';
@@ -106,7 +107,7 @@ const providerConfig = {
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
     <meta name="generator" content={Astro.generator} />
-    <title>Sign In | {title}</title>
+    <title>{formatPageTitle('Sign In')}</title>
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />

package/eventcatalog/src/features/auth/middleware/middleware-auth.ts

@@ -96,6 +96,14 @@ export function isMcpRoute(pathname: string) {
   return pathname === '/docs/mcp' || pathname.startsWith('/docs/mcp/');
 }
 
+// The Studio API answers in JSON, rather than sending callers to the sign-in page
+const isStudioApiRoute = (pathname: string) => pathname === '/api/studio' || pathname.startsWith('/api/studio/');
+const signInRequired = () =>
+  new Response(JSON.stringify({ error: 'Sign in to use this API' }), {
+    status: 401,
+    headers: { 'Content-Type': 'application/json' },
+  });
+
 export const authMiddleware: MiddlewareHandler = async (context, next) => {
   const { request, redirect, locals } = context;
   const url = new URL(request.url);
@@ -131,6 +139,7 @@ export const authMiddleware: MiddlewareHandler = async (context, next) => {
     const session = await getSession(request);
 
     if (!session) {
+      if (isStudioApiRoute(pathname)) return signInRequired();
       const callbackUrl = encodeURIComponent(pathname + url.search);
       return redirect(`/auth/login?callbackUrl=${callbackUrl}`);
     }
@@ -157,6 +166,7 @@ export const authMiddleware: MiddlewareHandler = async (context, next) => {
     typedLocals.matchesPattern = matchesPattern;
   } catch (error) {
     console.error('Session error:', error);
+    if (isStudioApiRoute(pathname)) return signInRequired();
     const callbackUrl = encodeURIComponent(pathname + url.search);
     return redirect(`/auth/login?callbackUrl=${callbackUrl}`);
   }
@@ -194,12 +204,22 @@ function normalizeUserData(session: any): NormalizedUser {
   }
 }
 
+// The host of a token's issuer (e.g. `dev-123.okta.com`), or '' when it isn't a URL
+const issuerHost = (issuer: unknown) => {
+  try {
+    return new URL(String(issuer)).hostname;
+  } catch {
+    return '';
+  }
+};
+
 function detectProvider(session: any): string {
   const account = session.account;
   if (account?.provider) return account.provider;
 
   if (session.user?.sub?.startsWith('auth0|')) return 'auth0';
-  if (session.user?.iss?.includes('okta.com') || session.user?.provider?.includes('okta')) return 'okta';
+  const host = issuerHost(session.user?.iss);
+  if (host === 'okta.com' || host.endsWith('.okta.com') || session.user?.provider?.includes('okta')) return 'okta';
   if (session.user?.iss?.includes('microsoft')) return 'microsoft';
   if (session.user?.iss?.includes('google')) return 'google';
 

package/eventcatalog/src/features/auth/unauthorized.astro

@@ -2,7 +2,7 @@
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 ---
 
-<VerticalSideBarLayout title="Unauthorized - EventCatalog" showNestedSideBar={false}>
+<VerticalSideBarLayout title="Unauthorized" showNestedSideBar={false}>
   <div class="flex h-[calc(100vh-120px)] bg-white">
     <main class="flex w-full items-center justify-center bg-white text-center sm:p-12">
       <div class="w-full max-w-xl text-center">

package/eventcatalog/src/features/fields/pages/fields.astro

@@ -7,7 +7,7 @@ import FieldsExplorer from '@components/FieldsExplorer/FieldsExplorer';
 export const prerender = false;
 ---
 
-<VerticalSideBarLayout title="Fields Explorer - EventCatalog" showNestedSideBar={false}>
+<VerticalSideBarLayout title="Fields Explorer" showNestedSideBar={false}>
   <style is:global>
     #eventcatalog-header {
       left: calc(var(--ec-vertical-nav-width, 14rem) + var(--ec-fields-sidebar-width, 320px)) !important;

package/eventcatalog/src/features/integrations/eventcatalog-features.ts

@@ -176,24 +176,30 @@ export default function eventCatalogIntegration(): AstroIntegration {
           });
         }
 
-        // Collaborative canvases in EventCatalog Studio (/studio lists them, /studio/new starts one). Their WebSocket
+        // What a server starts before anyone asks for it (the storage configured, migrated; Studio), called by
+        // `eventcatalog start` once it listens
+        if (isSSR()) {
+          params.injectRoute({
+            pattern: '/_eventcatalog/start',
+            entrypoint: path.join(packageDirectory, 'src/features/server/start.ts'),
+          });
+        }
+
+        // Collaborative canvases in EventCatalog Studio (/studio lists them, /studio?new=1 starts one). Their WebSocket
         // server is in integrations/studio-server.mjs.
         if (isCanvasEnabled()) {
           params.injectRoute({
             pattern: '/studio',
             entrypoint: path.join(packageDirectory, 'src/features/studio/pages/index.astro'),
           });
-          params.injectRoute({
-            pattern: '/studio/new',
-            entrypoint: path.join(packageDirectory, 'src/features/studio/pages/new.astro'),
-          });
           params.injectRoute({
             pattern: '/studio/[id]',
             entrypoint: path.join(packageDirectory, 'src/features/studio/pages/[id].astro'),
           });
+          // The Studio API (canvases as a whole: listing, creating, deleting)
           params.injectRoute({
-            pattern: '/_eventcatalog/studio/wake',
-            entrypoint: path.join(packageDirectory, 'src/features/studio/pages/wake.ts'),
+            pattern: '/api/studio/canvases/[...path]',
+            entrypoint: path.join(packageDirectory, 'src/features/studio/api/canvases.ts'),
           });
           params.injectRoute({
             pattern: '/webmcp-relay/[file]',