fix(web): stabilize home examples during startup (#7037)

* fix(web): stabilize home examples during startup

Keep the Home examples rail at stable geometry while Workspace discovery resolves, and reveal only the settled Workspace-scoped plugin catalog.

* fix(web): preserve Home example geometry while plugins load

Keep loading and settled Home example cards on one responsive size contract so plugin discovery cannot move the centered startup layout.

Add browser geometry coverage at desktop, tablet, and narrow viewports.

---------

Co-authored-by: Cheems <94773058+itscheems@users.noreply.github.com>

Author: open-design-crew[bot]

apps/web/src/components/HomeHero.tsx

@@ -18,6 +18,7 @@ import {
   useState,
 } from 'react';
 import { createPortal } from 'react-dom';
+import { VisuallyHidden } from '@open-design/components';
 import type {
   CSSProperties,
   DragEvent as ReactDragEvent,
@@ -2152,7 +2153,9 @@ export const HomeHero = forwardRef<HomeHeroHandle, Props>(function HomeHero(
         />
       ) : null}
 
-      {filteredExamplePlugins.length > 0 && activeChipId ? (
+      {pluginsLoading ? (
+        <PluginPromptPresetsLoading />
+      ) : filteredExamplePlugins.length > 0 && activeChipId ? (
         <PluginPromptPresets
           chipId={activeChipId}
           plugins={filteredExamplePlugins}
@@ -2236,6 +2239,32 @@ export const HomeHero = forwardRef<HomeHeroHandle, Props>(function HomeHero(
   );
 });
 
+function PluginPromptPresetsLoading() {
+  const { t } = useI18n();
+  return (
+    <div
+      className="home-hero__prompt-examples home-hero__plugin-presets-wrap"
+      data-testid="home-hero-examples-loading"
+      aria-busy="true"
+    >
+      <div className="home-hero__prompt-examples-title">
+        {t('homeHero.promptExamples')}
+      </div>
+      <div className="home-hero__rail-scroller">
+        <div className="home-hero__plugin-presets-loading" aria-hidden="true">
+          {Array.from({ length: 4 }, (_, index) => (
+            <span className="home-hero__plugin-preset-loading" key={index}>
+              <span className="home-hero__plugin-preset-loading-preview" />
+              <span className="home-hero__plugin-preset-loading-title" />
+            </span>
+          ))}
+        </div>
+      </div>
+      <VisuallyHidden>{t('common.loading')}</VisuallyHidden>
+    </div>
+  );
+}
+
 function PluginPromptPresets({
   activePluginId,
   chipId,

apps/web/src/components/HomeView.tsx

@@ -110,6 +110,7 @@ import {
   currentWorkspaceAccountGeneration,
   useTeamProjects,
   useWorkspaceContext,
+  workspaceResourceReadContext,
 } from '../collab/useWorkspaceContext';
 import { useWorkspaceInvalidation } from '../collab/workspace-events';
 import { useWorkspaceSnapshotActivation } from '../collab/workspace-snapshot-activation';
@@ -500,6 +501,7 @@ export function HomeView({
   const analytics = useAnalytics();
   const workspaceContextState = useWorkspaceContext();
   const { context: workspaceContext } = workspaceContextState;
+  const pluginCatalogWorkspaceContext = workspaceResourceReadContext(workspaceContextState);
   const lastSettledLocalCatalogScopeRef = useRef<LocalCatalogScope | null>(
     localCatalogScopeFromWorkspaceContext(workspaceContext),
   );
@@ -509,9 +511,14 @@ export function HomeView({
   }
   const pluginAccountGeneration = currentWorkspaceAccountGeneration();
   const pluginCatalogOptions = {
-    workspaceContext,
+    workspaceContext: pluginCatalogWorkspaceContext,
     accountGeneration: pluginAccountGeneration,
   };
+  // Keep the provisional local catalogue available for default-template
+  // routing while Workspace discovery runs, but never expose that provisional
+  // projection in HomeHero. The prop below keeps the Examples rail in its
+  // stable loading shell until the Workspace identity and its exact cache
+  // partition have both settled.
   const desiredPluginCatalogKey = workspaceContextState.identityChangePending
     ? null
     : pluginCatalogCacheKey(pluginCatalogOptions);
@@ -896,7 +903,7 @@ export function HomeView({
       return promise;
     };
     pluginCatalogReloadRef.current = load;
-    if (homeActiveRef.current && workspaceContext?.workspaceType !== 'team') load();
+    if (homeActiveRef.current && pluginCatalogWorkspaceContext?.workspaceType !== 'team') load();
     else pluginCatalogStaleRef.current = true;
     const onChanged = () => {
       // A mutation event is newer than any pending snapshot and must supersede
@@ -922,27 +929,27 @@ export function HomeView({
       }
       window.removeEventListener('open-design:plugins-changed', onChanged);
     };
-  }, [desiredPluginCatalogKey, workspaceContext?.workspaceType]);
+  }, [desiredPluginCatalogKey, pluginCatalogWorkspaceContext?.workspaceType]);
 
   useEffect(() => {
     if (!isActive || !desiredPluginCatalogKey || !pluginCatalogStaleRef.current) return;
-    if (workspaceContext?.workspaceType === 'team') return;
+    if (pluginCatalogWorkspaceContext?.workspaceType === 'team') return;
     pluginCatalogStaleRef.current = false;
     pluginCatalogReloadRef.current(true);
-  }, [desiredPluginCatalogKey, isActive, workspaceContext?.workspaceType]);
+  }, [desiredPluginCatalogKey, isActive, pluginCatalogWorkspaceContext?.workspaceType]);
 
   const handlePluginStreamActive = useWorkspaceSnapshotActivation({
-    enabled: isActive && workspaceContext?.workspaceType === 'team',
+    enabled: isActive && pluginCatalogWorkspaceContext?.workspaceType === 'team',
     identity: desiredPluginCatalogKey ?? 'no-plugin-catalog',
     refresh: () => { void pluginCatalogReloadRef.current(true, true); },
   });
 
   useWorkspaceInvalidation({}, {
     workspaceContext:
-      isActive && workspaceContext?.workspaceType === 'team'
-        ? workspaceContext
+      isActive && pluginCatalogWorkspaceContext?.workspaceType === 'team'
+        ? pluginCatalogWorkspaceContext
         : null,
-    enabled: isActive && workspaceContext?.workspaceType === 'team',
+    enabled: isActive && pluginCatalogWorkspaceContext?.workspaceType === 'team',
     // App owns the global Skill/Design System catch-up. Home only refreshes
     // its plugin projection.
     onActive: () => {
@@ -2978,7 +2985,11 @@ export function HomeView({
         onRemoveFile={removeStagedFile}
         onImportFigma={() => setFigmaModalOpen(true)}
         pluginOptions={plugins}
-        pluginsLoading={pluginsLoading}
+        pluginsLoading={
+          pluginsLoading
+          || workspaceContextState.loading
+          || workspaceContextState.identityChangePending === true
+        }
         skillOptions={selectableSkills}
         skillsLoading={skillsLoading}
         mcpOptions={enabledMcpServers}

apps/web/src/styles/home/home-hero.css

@@ -2497,6 +2497,12 @@
    centered hero (they collapse to 0 when the viewport is narrower than the
    hero cap and the two widths coincide). */
 .home-hero__plugin-presets-wrap {
+  /* One geometry contract for both the loading shell and settled cards.
+     The fixed card height is the natural rendered height of the preview,
+     gap, caption line, padding, and border rounded to a whole pixel. */
+  --home-plugin-preset-width: 248px;
+  --home-plugin-preset-preview-h: 150px;
+  --home-plugin-preset-card-h: 194px;
   width: 100cqw;
   max-width: 100cqw;
   margin-inline: calc((100% - 100cqw) / 2);
@@ -2506,7 +2512,10 @@
    scrolling presets row (not the title above it). */
 .home-hero__rail-scroller {
   position: relative;
-  min-height: 194px;
+  /* Both preset rows use 1px top + 8px bottom padding. Reserving that
+     together with the shared card height prevents the centered Home layout
+     from moving when loading content is replaced. */
+  min-height: calc(var(--home-plugin-preset-card-h) + 9px);
 }
 
 .home-hero__plugin-presets {
@@ -2523,31 +2532,67 @@
 }
 .home-hero__plugin-presets::-webkit-scrollbar { display: none; }
 
+/* Keep the Examples rail's final geometry reserved while the Workspace-scoped
+   plugin catalogue resolves. These placeholders are deliberately static: the
+   real cards already own their entrance animation, and animating the loading
+   shell would recreate the startup twitch this state is meant to prevent. */
+.home-hero__plugin-presets-loading {
+  display: flex;
+  align-items: stretch;
+  gap: 10px;
+  overflow: hidden;
+  padding: 1px 2px 8px;
+}
+.home-hero__plugin-preset-loading {
+  flex: 0 0 var(--home-plugin-preset-width);
+  min-width: 0;
+  height: var(--home-plugin-preset-card-h);
+  min-height: var(--home-plugin-preset-card-h);
+  display: grid;
+  grid-template-rows: var(--home-plugin-preset-preview-h) minmax(0, auto);
+  gap: 8px;
+  overflow: hidden;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  background: var(--bg-panel);
+  box-shadow: var(--shadow-xs);
+}
+.home-hero__plugin-preset-loading-preview {
+  display: block;
+  background: var(--bg-subtle);
+  border-bottom: 1px solid color-mix(in srgb, var(--border) 72%, transparent);
+}
+.home-hero__plugin-preset-loading-title {
+  display: block;
+  width: 46%;
+  height: 10px;
+  margin: 1px 10px 0;
+  border-radius: var(--radius-pill);
+  background: color-mix(in srgb, var(--text-faint) 18%, var(--bg-subtle));
+}
+
 /* Each preset is wrapped in a positioning cell so the "Open as project"
    overlay can sit over the thumbnail without nesting a button inside the
    card button. The flex sizing lives on the cell; the card button fills it. */
 .home-hero__plugin-preset-cell {
   position: relative;
-  flex: 0 0 248px;
+  flex: 0 0 var(--home-plugin-preset-width);
   min-width: 0;
   display: flex;
   /* One source for the preview row's height: the preview box below pins
      itself to it. */
-  --preset-preview-h: 150px;
+  --preset-preview-h: var(--home-plugin-preset-preview-h);
 }
 
 .home-hero__plugin-preset {
   appearance: none;
   position: relative;
   width: 100%;
-  height: auto;
-  /* Low enough that the caption row hugs its text (150 preview + 8 gap +
-     one 16px line + 6px pad ≈ 180); a taller min just reads as dead space
-     under the title. */
-  min-height: 172px;
+  height: var(--home-plugin-preset-card-h);
+  min-height: var(--home-plugin-preset-card-h);
   min-width: 0;
   display: grid;
-  grid-template-rows: 150px minmax(0, auto);
+  grid-template-rows: var(--home-plugin-preset-preview-h) minmax(0, auto);
   gap: 8px;
   padding: 0;
   border: 1px solid var(--border);
@@ -2883,22 +2928,17 @@
 }
 
 @media (max-width: 900px) {
+  .home-hero__plugin-presets-wrap {
+    --home-plugin-preset-width: 224px;
+    --home-plugin-preset-preview-h: 136px;
+    --home-plugin-preset-card-h: 180px;
+  }
   .home-hero__title {
     font-size: 38.4px;
   }
   .home-hero__prompt-examples-grid {
     grid-template-columns: repeat(2, minmax(0, 1fr));
   }
-  .home-hero__plugin-preset-cell {
-    flex-basis: 224px;
-  }
-  .home-hero__plugin-preset {
-    min-height: 170px;
-    grid-template-rows: 136px minmax(0, auto);
-  }
-  .home-hero__plugin-preset-preview {
-    min-height: 136px;
-  }
   .home-hero__plugin-preset-preview .plugins-home__html-iframe {
     transform: scale(0.146);
   }
@@ -2934,23 +2974,18 @@
 }
 
 @media (max-width: 560px) {
+  .home-hero__plugin-presets-wrap {
+    --home-plugin-preset-width: 208px;
+    --home-plugin-preset-preview-h: 126px;
+    --home-plugin-preset-card-h: 170px;
+  }
   .home-hero__type-tabs {
     justify-content: flex-start;
     padding: 0;
   }
   .home-hero__prompt-examples-grid {
     grid-template-columns: 1fr;
   }
-  .home-hero__plugin-preset-cell {
-    flex-basis: 208px;
-  }
-  .home-hero__plugin-preset {
-    min-height: 160px;
-    grid-template-rows: 126px minmax(0, auto);
-  }
-  .home-hero__plugin-preset-preview {
-    min-height: 126px;
-  }
   .home-hero__plugin-preset-preview .plugins-home__html-iframe {
     transform: scale(0.134);
   }

apps/web/tests/components/HomeHero.rail.test.tsx

@@ -285,6 +285,15 @@ describe('HomeHero intent rail', () => {
     expect(screen.queryByTestId('home-hero-active-example')).toBeNull();
   });
 
+  it('reserves the example rail while the plugin catalog is still loading', () => {
+    renderHero({ activeChipId: null, pluginsLoading: true });
+
+    const loading = screen.getByTestId('home-hero-examples-loading');
+    expect(loading.getAttribute('aria-busy')).toBe('true');
+    expect(screen.queryByTestId('home-hero-prompt-examples')).toBeNull();
+    expect(screen.queryByTestId('home-hero-plugin-presets')).toBeNull();
+  });
+
   it('shows matching plugin presets in the example prompt area for the selected tab', () => {
     const deckPlugin = makePlugin('example-deck-a', 'deck', 'Investor deck');
     const imagePlugin = makePlugin('example-image-a', 'image', 'Product image');

apps/web/tests/components/HomeView.plugin-workspace-scope.test.tsx

@@ -205,6 +205,57 @@ describe('HomeView workspace-scoped plugin catalog', () => {
     workspaceInvalidationHarness.autoActivate = true;
   });
 
+  it('masks the provisional catalog until the first Workspace-scoped read settles', async () => {
+    const pluginRequests: Headers[] = [];
+    vi.stubGlobal('fetch', vi.fn<typeof fetch>(async (input, init) => {
+      if (String(input) === '/api/plugins') {
+        const headers = new Headers(init?.headers);
+        pluginRequests.push(headers);
+        const pluginId = headers.has('x-od-workspace-id')
+          ? 'scoped-plugin'
+          : 'provisional-plugin';
+        return new Response(JSON.stringify({ plugins: [plugin(pluginId)] }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+      return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } });
+    }));
+    workspaceMock.state = {
+      context: null,
+      loading: true,
+      identityChangePending: false,
+      failure: undefined,
+    };
+    const view = renderHome();
+
+    await waitFor(() => expect(pluginRequests).toHaveLength(1));
+    expect(pluginRequests[0]?.has('x-od-workspace-id')).toBe(false);
+    expect(screen.getByTestId('plugin-catalog').textContent).toBe('loading');
+
+    workspaceMock.state = {
+      context: teamContext('workspace-startup', 'member-startup'),
+      loading: false,
+      identityChangePending: false,
+      failure: undefined,
+    };
+    view.rerender(
+      <HomeView
+        projects={[]}
+        onSubmit={() => undefined}
+        onOpenProject={() => undefined}
+        onViewAllProjects={() => undefined}
+      />,
+    );
+
+    await waitFor(() => expect(pluginRequests).toHaveLength(2));
+    expect(pluginRequests[1]?.get('x-od-workspace-id')).toBe('workspace-startup');
+    expect(pluginRequests[1]?.get('x-od-workspace-member-id')).toBe('member-startup');
+    await waitFor(() => {
+      expect(screen.getByTestId('plugin-catalog').textContent).toBe('scoped-plugin');
+    });
+  });
+
   it('parks hidden plugin invalidations and performs one bounded catch-up when Home activates', async () => {
     let pluginReads = 0;
     vi.stubGlobal('fetch', vi.fn<typeof fetch>(async (input) => {