@storybook-astro/framework 1.6.0 → 1.7.0-canary.2

package/src/lib/reconstruct-component-args.ts

@@ -0,0 +1,155 @@
+import { isAstroComponentFactory, isAstroComponentMarker } from '@storybook-astro/renderer/types';
+
+/**
+ * Resolves Astro component references that a story passed as props or slot
+ * content back into something the Astro Container can render.
+ *
+ * A component reference arrives either as a serialized marker (the browser /
+ * dev / server path, where it crossed a JSON boundary) or as a real component
+ * factory (the Vitest / portable-stories path, which imports `.astro` files
+ * directly). Both are handled.
+ *
+ * - **Props**: resolved to the real component factory and passed through, so the
+ *   parent template renders them with `<Comp />` (the Container supports this).
+ * - **Slots**: rendered to an HTML string, because the Container only accepts
+ *   string slot content — a factory passed as a slot is stringified verbatim.
+ *
+ * Both callbacks are injected so this is reusable across the dev/server handler
+ * (which loads by moduleId and renders via its container) and the testing path
+ * (where factories are already in hand).
+ */
+type LoadComponent = (moduleId: string) => Promise<unknown>;
+type RenderToHtml = (component: unknown) => Promise<string>;
+
+// Guards against pathological/cyclic arg objects. Component references are leaf
+// replacements, so real nesting is shallow; this is just insurance.
+const MAX_DEPTH = 10;
+
+/**
+ * Resolves component references in **props** back to real component factories,
+ * so the parent template renders them with `<Comp />`. Run this before the
+ * normal arg processing (image/date/sanitize) — factories pass through those
+ * untouched, and a resolved prop must exist before the parent renders.
+ */
+export async function reconstructProps(
+  args: Record<string, unknown>,
+  callbacks: { loadComponent: LoadComponent }
+): Promise<Record<string, unknown>> {
+  return (await resolvePropValue(args, callbacks, 0)) as Record<string, unknown>;
+}
+
+/**
+ * Resolves component references in **slots** to HTML strings (the Container only
+ * accepts string slots). Run this *after* sanitization so a component's rendered
+ * markup — trusted, like a prop-rendered component — isn't stripped by the slot
+ * HTML allowlist, while plain-string slots still are.
+ */
+export async function reconstructSlots(
+  slots: Record<string, unknown>,
+  callbacks: { loadComponent: LoadComponent; renderToHtml: RenderToHtml }
+): Promise<Record<string, unknown>> {
+  const out: Record<string, unknown> = {};
+
+  for (const [name, value] of Object.entries(slots)) {
+    out[name] = await resolveSlotValue(name, value, callbacks);
+  }
+
+  return out;
+}
+
+/**
+ * Walks a prop value, replacing component references with real factories.
+ * Returns the original reference untouched when nothing changed, so unrelated
+ * args keep their identity (e.g. `ImageMetadata` objects the image pipeline
+ * later inspects).
+ */
+async function resolvePropValue(
+  value: unknown,
+  callbacks: { loadComponent: LoadComponent },
+  depth: number
+): Promise<unknown> {
+  if (isAstroComponentMarker(value)) {
+    return callbacks.loadComponent(value.moduleId);
+  }
+
+  // Already a real factory (testing path) — pass it straight through as a prop.
+  if (isAstroComponentFactory(value)) {
+    return value;
+  }
+
+  if (depth >= MAX_DEPTH) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    const resolved = await Promise.all(
+      value.map((item) => resolvePropValue(item, callbacks, depth + 1))
+    );
+
+    return resolved.some((item, index) => item !== value[index]) ? resolved : value;
+  }
+
+  if (isPlainObject(value)) {
+    let changed = false;
+    const out: Record<string, unknown> = {};
+
+    for (const [key, nested] of Object.entries(value)) {
+      const resolved = await resolvePropValue(nested, callbacks, depth + 1);
+
+      if (resolved !== nested) {
+        changed = true;
+      }
+
+      out[key] = resolved;
+    }
+
+    return changed ? out : value;
+  }
+
+  return value;
+}
+
+async function resolveSlotValue(
+  name: string,
+  value: unknown,
+  callbacks: { loadComponent: LoadComponent; renderToHtml: RenderToHtml }
+): Promise<unknown> {
+  // An array slot (list of components and/or strings) is concatenated into one
+  // HTML string, which is what the Container expects for a single slot.
+  if (Array.isArray(value)) {
+    const parts = await Promise.all(value.map((item) => resolveSlotValue(name, item, callbacks)));
+
+    return parts.join('');
+  }
+
+  if (isAstroComponentMarker(value)) {
+    const component = await callbacks.loadComponent(value.moduleId);
+
+    return renderSlotComponent(name, component, callbacks);
+  }
+
+  if (isAstroComponentFactory(value)) {
+    return renderSlotComponent(name, value, callbacks);
+  }
+
+  // Plain HTML string (or anything else) passes through unchanged.
+  return value;
+}
+
+async function renderSlotComponent(
+  name: string,
+  component: unknown,
+  callbacks: { renderToHtml: RenderToHtml }
+): Promise<string> {
+  try {
+    return await callbacks.renderToHtml(component);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+
+    throw new Error(`Failed to render Astro component passed to slot "${name}": ${message}`);
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/src/lib/separate-story-slots.ts

@@ -0,0 +1,20 @@
+/**
+ * Splits a story's `args` into component props and slot content. Slot content
+ * lives under the reserved `slots` key (`args.slots.<name>`); everything else is
+ * a prop. Returns `{}` for slots when `args.slots` is absent or not an object.
+ */
+export function separateStorySlots(storyArgs: Record<string, unknown>): {
+  componentArgs: Record<string, unknown>;
+  storySlots: Record<string, unknown>;
+} {
+  const componentArgs = { ...storyArgs };
+  const storySlots = componentArgs.slots;
+
+  delete componentArgs.slots;
+
+  if (typeof storySlots !== 'object' || storySlots === null) {
+    return { componentArgs, storySlots: {} };
+  }
+
+  return { componentArgs, storySlots: storySlots as Record<string, unknown> };
+}

package/src/preset.ts

@@ -1,4 +1,5 @@
 import { dirname } from 'node:path';
+import { version as viteVersion } from 'vite';
 import type { StorybookConfigVite, FrameworkOptions } from './types.ts';
 import { vitePluginStorybookAstroMiddleware } from './viteStorybookAstroMiddlewarePlugin.ts';
 import { viteStorybookRendererFallbackPlugin } from './viteStorybookRendererFallbackPlugin.ts';
@@ -205,8 +206,8 @@ export const viteFinal: StorybookConfigVite['viteFinal'] = async (config, storyb
   }
   // Mark integration virtual modules as external so the dep bundler doesn't
   // try to resolve them (they are Vite virtual modules with no real package).
-  // Set both esbuildOptions (Vite ≤7) and rolldownOptions (Vite 8+, Rolldown)
-  // so the correct key is populated regardless of Vite version.
+  // Vite ≤7 reads these from esbuildOptions; Vite 8+ uses Rolldown and reads
+  // them from rolldownOptions. We populate whichever key the running Vite uses.
   const integrationVirtualModules = [
     'virtual:@astrojs/vue/app',
     'virtual:astro:vue-app',
@@ -215,16 +216,21 @@ export const viteFinal: StorybookConfigVite['viteFinal'] = async (config, storyb
     'astro:toolbar:internal'
   ];
 
-  // Vite ≤7 (esbuild-based optimizer)
-  if (!finalConfig.optimizeDeps.esbuildOptions) {
-    finalConfig.optimizeDeps.esbuildOptions = {};
-  }
-  if (!finalConfig.optimizeDeps.esbuildOptions.external) {
-    finalConfig.optimizeDeps.esbuildOptions.external = [];
-  }
-  for (const mod of integrationVirtualModules) {
-    if (!finalConfig.optimizeDeps.esbuildOptions.external.includes(mod)) {
-      finalConfig.optimizeDeps.esbuildOptions.external.push(mod);
+  const viteMajor = Number.parseInt(viteVersion, 10);
+
+  // Vite ≤7 (esbuild-based optimizer). On Vite 8+ setting esbuildOptions logs a
+  // deprecation warning, so only touch it on older Vite.
+  if (viteMajor < 8) {
+    if (!finalConfig.optimizeDeps.esbuildOptions) {
+      finalConfig.optimizeDeps.esbuildOptions = {};
+    }
+    if (!finalConfig.optimizeDeps.esbuildOptions.external) {
+      finalConfig.optimizeDeps.esbuildOptions.external = [];
+    }
+    for (const mod of integrationVirtualModules) {
+      if (!finalConfig.optimizeDeps.esbuildOptions.external.includes(mod)) {
+        finalConfig.optimizeDeps.esbuildOptions.external.push(mod);
+      }
     }
   }
 
@@ -237,6 +243,48 @@ export const viteFinal: StorybookConfigVite['viteFinal'] = async (config, storyb
   );
   optimizeDepsMut.rolldownOptions = rolldownOpts;
 
+  // Vite 8 dev-server compatibility (Astro 7+). Vite ≤7 (Astro 5/6) is unaffected.
+  if (configType === 'DEVELOPMENT' && viteMajor >= 8) {
+    // 1. Drop @vitejs/plugin-react's Vite 8 native Fast Refresh wrapper. Under
+    //    Vite 8 the plugin delegates Fast Refresh to a Rolldown builtin
+    //    (`builtin:vite-react-refresh-wrapper`) that throws
+    //    "Missing field `moduleType`" while transforming Storybook's iframe.html
+    //    inline bootstrap script — 500-ing every preview load. There is no
+    //    config opt-out, so we remove the plugin. React components still render;
+    //    only Fast Refresh is lost (component edits full-reload instead).
+    const stripReactRefreshWrapper = (plugins: unknown[]): unknown[] =>
+      plugins
+        .map((plugin) => (Array.isArray(plugin) ? stripReactRefreshWrapper(plugin) : plugin))
+        .filter(
+          (plugin) =>
+            !(
+              plugin &&
+              typeof plugin === 'object' &&
+              (plugin as { name?: string }).name === 'vite:react:refresh-wrapper'
+            )
+        );
+
+    finalConfig.plugins = stripReactRefreshWrapper(
+      finalConfig.plugins ?? []
+    ) as typeof finalConfig.plugins;
+
+    // 2. Exclude the Storybook renderer entry-previews from dependency
+    //    optimization. Some ship non-JS source (e.g. `@storybook/svelte`'s
+    //    `.svelte` files) that the esbuild dep scanner cannot load
+    //    ("No loader is configured for .svelte"), which fails optimization and
+    //    504s every renderer entry. Serving them as source lets the framework's
+    //    own Vite plugins transform them.
+    const entryPreviews = integrations
+      .map((integration) => integration.storybookEntryPreview)
+      .filter((specifier): specifier is string => Boolean(specifier));
+
+    for (const specifier of entryPreviews) {
+      if (!finalConfig.optimizeDeps.exclude.includes(specifier)) {
+        finalConfig.optimizeDeps.exclude.push(specifier);
+      }
+    }
+  }
+
   return finalConfig;
 };
 

package/src/productionRenderRuntime.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test, vi } from 'vitest';
+import {
+  renderProductionStoryToHtml,
+  type ProductionRenderRuntime,
+  type ProductionStoryEntry
+} from './productionRenderRuntime.ts';
+
+const resolveFrom = '/project';
+
+const story: ProductionStoryEntry = {
+  id: 'components-button--primary',
+  importPath: './src/Button.stories.ts',
+  componentPath: './src/Button.astro',
+  exportName: 'Primary',
+  title: 'Components/Button',
+  name: 'Primary'
+};
+
+/** A stand-in Astro component factory; only its identity and `function`-ness matter here. */
+function ButtonAstro() {
+  return '';
+}
+
+function createRuntime(storyModule: Record<string, unknown>): {
+  runtime: ProductionRenderRuntime;
+  renderAstroStory: ReturnType<typeof vi.fn>;
+} {
+  const renderAstroStory = vi.fn(async () => '<button>rendered</button>');
+
+  return {
+    runtime: {
+      loadModule: async () => storyModule,
+      renderAstroStory,
+      close: async () => {}
+    },
+    renderAstroStory
+  };
+}
+
+describe('renderProductionStoryToHtml', () => {
+  test('CSF3: reads component from the default export and merges meta + story args', async () => {
+    const { runtime, renderAstroStory } = createRuntime({
+      default: { component: ButtonAstro, args: { label: 'Meta', size: 'lg' } },
+      Primary: { args: { label: 'Primary' } }
+    });
+
+    const html = await renderProductionStoryToHtml({ story, runtime, resolveFrom });
+
+    expect(html).toBe('<button>rendered</button>');
+    expect(renderAstroStory).toHaveBeenCalledWith(
+      expect.objectContaining({
+        component: '/project/src/Button.astro',
+        args: { label: 'Primary', size: 'lg' }
+      })
+    );
+  });
+
+  test('CSF4 factory: reads component and args from the story export meta with no default export', async () => {
+    const { runtime, renderAstroStory } = createRuntime({
+      // Shape produced by `meta.story()` in Storybook's CSF factories.
+      Primary: {
+        _tag: 'Story',
+        input: { args: { label: 'Primary' } },
+        meta: {
+          _tag: 'Meta',
+          input: { component: ButtonAstro, args: { label: 'Meta', size: 'lg' } }
+        }
+      }
+    });
+
+    const html = await renderProductionStoryToHtml({ story, runtime, resolveFrom });
+
+    expect(html).toBe('<button>rendered</button>');
+    expect(renderAstroStory).toHaveBeenCalledWith(
+      expect.objectContaining({
+        component: '/project/src/Button.astro',
+        args: { label: 'Primary', size: 'lg' }
+      })
+    );
+  });
+
+  test('skips stories that override the component with a non-Astro render', async () => {
+    function OtherComponent() {
+      return '';
+    }
+
+    const { runtime, renderAstroStory } = createRuntime({
+      default: { component: ButtonAstro },
+      Primary: { component: OtherComponent }
+    });
+
+    const html = await renderProductionStoryToHtml({ story, runtime, resolveFrom });
+
+    expect(html).toBeUndefined();
+    expect(renderAstroStory).not.toHaveBeenCalled();
+  });
+});

package/src/productionRenderRuntime.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 import { createAstroRenderHandler, type HandlerProps } from './astroRenderHandler.ts';
+import { separateStorySlots } from './lib/separate-story-slots.ts';
 import type { Integration } from './integrations/index.ts';
 import type { SanitizationOptions } from './lib/sanitization.ts';
 import type { FrameworkOptions } from './types.ts';
@@ -107,25 +108,23 @@ export async function renderProductionStoryToHtml(options: {
   const storyModulePath = resolveProjectImportPath(options.story.importPath, options.resolveFrom);
   const componentPath = resolveProjectImportPath(options.story.componentPath, options.resolveFrom);
   const storyModule = await options.runtime.loadModule(storyModulePath);
-  const defaultStoryMeta = isRecord(storyModule.default) ? storyModule.default : {};
-  const rawStoryExport: unknown = storyModule[options.story.exportName];
-  const selectedStoryExport: Record<string, unknown> = isRecord(rawStoryExport) ? rawStoryExport : {};
+  const { metaComponent, metaArgs, storyComponent, storyLevelArgs } = resolveStoryAnnotations(
+    storyModule,
+    options.story.exportName
+  );
 
-  if (typeof defaultStoryMeta.component !== 'function') {
+  if (typeof metaComponent !== 'function') {
     throw new Error(
-      `Unable to prerender story "${options.story.id}". Missing default export component in ${options.story.importPath}.`
+      `Unable to prerender story "${options.story.id}". Missing component in ${options.story.importPath}.`
     );
   }
 
   // Build-time prerender only supports stories that keep the meta-level Astro component.
-  if (selectedStoryExport.component && selectedStoryExport.component !== defaultStoryMeta.component) {
+  if (storyComponent && storyComponent !== metaComponent) {
     return undefined;
   }
 
-  const storyArgs = mergeMetaArgsWithStoryArgs(
-    toRecord(defaultStoryMeta.args),
-    toRecord(selectedStoryExport.args)
-  );
+  const storyArgs = mergeMetaArgsWithStoryArgs(metaArgs, storyLevelArgs);
   const { componentArgs, storySlots } = separateStorySlots(storyArgs);
 
   return options.runtime.renderAstroStory({
@@ -140,6 +139,43 @@ export async function renderProductionStoryToHtml(options: {
   });
 }
 
+/**
+ * Reads the meta- and story-level component and args for one story export,
+ * supporting both authoring styles:
+ *
+ * - CSF3: the meta is the module's default export and the named export holds the
+ *   story's own args/component.
+ * - CSF4 factories: there is no default export. The named export is a
+ *   `{ _tag: 'Story', input, meta }` object produced by `meta.story()`, where the
+ *   meta-level annotations live on `meta.input`.
+ */
+function resolveStoryAnnotations(storyModule: LoadedStoryModule, exportName: string) {
+  const rawStoryExport: unknown = storyModule[exportName];
+
+  if (isRecord(rawStoryExport) && rawStoryExport._tag === 'Story') {
+    const storyInput = toRecord(rawStoryExport.input) ?? {};
+    const meta = isRecord(rawStoryExport.meta) ? rawStoryExport.meta : {};
+    const metaInput = toRecord(meta.input) ?? {};
+
+    return {
+      metaComponent: metaInput.component,
+      metaArgs: toRecord(metaInput.args),
+      storyComponent: storyInput.component,
+      storyLevelArgs: toRecord(storyInput.args)
+    };
+  }
+
+  const defaultStoryMeta = isRecord(storyModule.default) ? storyModule.default : {};
+  const selectedStoryExport = isRecord(rawStoryExport) ? rawStoryExport : {};
+
+  return {
+    metaComponent: defaultStoryMeta.component,
+    metaArgs: toRecord(defaultStoryMeta.args),
+    storyComponent: selectedStoryExport.component,
+    storyLevelArgs: toRecord(selectedStoryExport.args)
+  };
+}
+
 function resolveProjectImportPath(importPath: string, resolveFrom: string) {
   if (importPath.startsWith('./') || importPath.startsWith('../')) {
     return resolve(resolveFrom, importPath);
@@ -158,25 +194,6 @@ function mergeMetaArgsWithStoryArgs(
   };
 }
 
-function separateStorySlots(storyArgs: Record<string, unknown>) {
-  const componentArgs = { ...storyArgs };
-  const storySlots = componentArgs.slots;
-
-  delete componentArgs.slots;
-
-  if (!isRecord(storySlots)) {
-    return {
-      componentArgs,
-      storySlots: {}
-    };
-  }
-
-  return {
-    componentArgs,
-    storySlots: storySlots as Record<string, string>
-  };
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }

package/src/storySsrVite.ts

@@ -253,17 +253,34 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
 
-// Stubs Storybook's browser-only packages so story files that import docs
-// blocks (e.g. `import { Controls } from '@storybook/blocks'`) don't
-// trigger `document is not defined` during SSR prerendering. We only need
-// component/args from story modules — docs block components are never called.
+// Stubs Storybook's browser-only docs packages so a project's preview config
+// doesn't crash the SSR prerender. Stories import `@storybook/preview`, which
+// loads `.storybook/preview.ts`, which commonly registers the docs addon
+// (`import addonDocs from '@storybook/addon-docs'`). The docs addon pulls in
+// Storybook's UI kit, which reads `document.documentElement` at module load and
+// throws `document is not defined` under Node. The docs UI never runs during
+// prerendering — we only need each story's component and args — so replacing it
+// with a no-op is safe.
+//
+// `@storybook/addon-docs`'s default export is called as a function in preview
+// config (`addonDocs()`), so the stub exports a callable no-op. `blocks` are the
+// docs block components (used only inside MDX, which is not prerendered), and
+// `@storybook/blocks` is the pre-Storybook-10 path for those same blocks.
 function createStorybookBrowserStubPlugin(): Plugin {
+  const STUBBED_SPECIFIERS = new Set([
+    '@storybook/addon-docs',
+    '@storybook/addon-docs/blocks',
+    '@storybook/blocks'
+  ]);
   const STUB_ID = '\0storybook-astro-browser-stub';
 
   return {
     name: 'storybook-astro:storybook-browser-stubs',
+    // Must run before Astro's resolvers, which would otherwise resolve these
+    // bare specifiers to their real (browser-only) files before we can stub them.
+    enforce: 'pre',
     resolveId(id: string) {
-      if (id === '@storybook/blocks') {
+      if (STUBBED_SPECIFIERS.has(id)) {
         return STUB_ID;
       }
 
@@ -271,7 +288,7 @@ function createStorybookBrowserStubPlugin(): Plugin {
     },
     load(id: string) {
       if (id === STUB_ID) {
-        return 'export {};';
+        return 'export default () => ({});';
       }
 
       return null;

package/src/testing/astro-runtime.ts

@@ -6,6 +6,10 @@ import { resolveTestingProjectRoot } from './project-root.ts';
 import { runWithWorkingDirectory } from './working-directory.ts';
 import { getComponentModuleId, isAstroComponentFactory, isStorybookAstroClientStub } from './component-utils.ts';
 import { ssrLoadModuleWithFsFallback } from '../lib/ssr-load-module-with-fs-fallback.ts';
+import { separateStorySlots } from '../lib/separate-story-slots.ts';
+import { reconstructProps, reconstructSlots } from '../lib/reconstruct-component-args.ts';
+import { patchCreateAstroCompat, markRawSlots } from '../astroRenderHandler.ts';
+import { serializeAstroComponentMarkers } from '@storybook-astro/renderer/types';
 import type { ComposedStory } from './types.ts';
 import { renderViaTestingRendererDaemon } from './renderer-daemon.ts';
 
@@ -16,7 +20,13 @@ const astroSsrViteServerPromises = new Map<string, Promise<ViteDevServer>>();
 
 const astroSsrHandlerPromises = new Map<
   string,
-  Promise<(data: { component: string; args?: Record<string, unknown> }) => Promise<string>>
+  Promise<
+    (data: {
+      component: string;
+      args?: Record<string, unknown>;
+      slots?: Record<string, unknown>;
+    }) => Promise<string>
+  >
 >();
 
 const testingIntegrationsCache = new Map<string, StorybookAstroIntegration[]>();
@@ -115,6 +125,14 @@ async function resolveAstroComponent(component: unknown, resolveFrom: string) {
   return resolvedComponent;
 }
 
+function setRenderedHtml(html: string) {
+  if (typeof document !== 'undefined') {
+    document.body.innerHTML = html;
+  }
+
+  return html;
+}
+
 async function renderAstroComponentToDom(
   component: unknown,
   args: Record<string, unknown>,
@@ -122,21 +140,26 @@ async function renderAstroComponentToDom(
 ) {
   const moduleId = getComponentModuleId(component);
 
+  // Split slot content from props, then serialize any Astro component passed as
+  // a prop or slot into a moduleId marker. The handler reconstructs each marker —
+  // loading the real server component by moduleId — so a story can nest Astro
+  // components without the unrenderable client stub leaking through.
+  const { componentArgs, storySlots } = separateStorySlots(args);
+  const serializedArgs = serializeAstroComponentMarkers(componentArgs) as Record<string, unknown>;
+  const serializedSlots = serializeAstroComponentMarkers(storySlots) as Record<string, unknown>;
+
   if (moduleId) {
     try {
       // Fast path: reuse a single shared SSR daemon instead of spinning SSR in each worker.
       const html = await renderViaTestingRendererDaemon({
         resolveFrom,
         component: moduleId,
-        args
+        args: serializedArgs,
+        slots: serializedSlots
       });
 
       if (typeof html === 'string') {
-        if (typeof document !== 'undefined') {
-          document.body.innerHTML = html;
-        }
-
-        return html;
+        return setRenderedHtml(html);
       }
     } catch {
       // Fall back to in-worker rendering below when daemon render fails.
@@ -146,14 +169,11 @@ async function renderAstroComponentToDom(
       const handler = await getAstroSsrHandler(resolveFrom);
       const html = await handler({
         component: moduleId,
-        args
+        args: serializedArgs,
+        slots: serializedSlots
       });
 
-      if (typeof document !== 'undefined') {
-        document.body.innerHTML = html;
-      }
-
-      return html;
+      return setRenderedHtml(html);
     } catch {
       // Fall back to direct Container rendering below
     }
@@ -161,20 +181,31 @@ async function renderAstroComponentToDom(
 
   const resolvedComponent = await resolveAstroComponent(component, resolveFrom);
   const container = await getAstroContainer();
-  
+
   if (!container) {
     throw new Error('Failed to initialize Astro container for rendering');
   }
-  
-  const html = await container.renderToString(resolvedComponent, {
-    props: args
+
+  // The direct fallback has no handler, so reconstruct nested components here:
+  // load each marker's real server module by id and render slot markers to HTML.
+  const loadComponent = async (id: string) => {
+    const viteServer = await getAstroSsrViteServer(resolveFrom);
+    const mod = (await ssrLoadModuleWithFsFallback(viteServer, id)) as Record<string, unknown>;
+
+    return patchCreateAstroCompat(mod.default);
+  };
+  const reconstructedArgs = await reconstructProps(serializedArgs, { loadComponent });
+  const reconstructedSlots = await reconstructSlots(serializedSlots, {
+    loadComponent,
+    renderToHtml: (child) => container.renderToString(child, {})
   });
 
-  if (typeof document !== 'undefined') {
-    document.body.innerHTML = html;
-  }
+  const html = await container.renderToString(resolvedComponent, {
+    props: reconstructedArgs,
+    slots: markRawSlots(reconstructedSlots)
+  });
 
-  return html;
+  return setRenderedHtml(html);
 }
 
 async function renderComposedStory(story: ComposedStory) {

package/src/vitePluginAstroComponentMarker.ts

@@ -33,7 +33,12 @@ export function vitePluginAstroComponentMarker(): PluginOption {
       // Only process main .astro modules (not sub-modules like ?astro&type=style)
       if (!id.endsWith('.astro')) {return null;}
 
-      // Detect the Astro 6 client-side stub pattern
+      // Detect the Astro client-side stub pattern. Astro 6's Go compiler and
+      // Astro 7's Rust compiler (now the default) both emit this same error
+      // string in the browser stub, so the single check covers Astro 5–7. If a
+      // future compiler changes this text, components will silently miss the
+      // `isAstroComponentFactory = true` marker and render blank — update the
+      // string here if that happens.
       if (!code.includes('Astro components cannot be used in the browser')) {return null;}
 
       const moduleId = id;