@storybook-astro/framework 1.0.3 → 1.1.1

package/src/lib/sanitization.ts

@@ -160,6 +160,20 @@ export function sanitizeRenderPayload(
   };
 }
 
+export function serializeSanitizationOptions(options?: SanitizationOptions): string {
+  if (!options) {
+    return 'undefined';
+  }
+
+  assertNoFunctions(options.sanitizeHtml, 'framework.options.sanitization.sanitizeHtml');
+
+  const state = {
+    seen: new WeakSet<object>()
+  };
+
+  return serializeValue(options, 'framework.options.sanitization', state);
+}
+
 function mergeSanitizeHtmlOptions(userOptions?: IOptions): IOptions {
   const merged: IOptions = {
     ...DEFAULT_SANITIZE_HTML_OPTIONS,
@@ -287,6 +301,96 @@ function matchesPathPattern(path: string, pattern: string): boolean {
   return matchSegments(pathSegments, patternSegments);
 }
 
+function serializeValue(value: unknown, path: string, state: { seen: WeakSet<object> }): string {
+  if (value === null) {
+    return 'null';
+  }
+
+  if (value === undefined) {
+    return 'undefined';
+  }
+
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return JSON.stringify(value);
+  }
+
+  if (value instanceof RegExp) {
+    return value.toString();
+  }
+
+  if (Array.isArray(value)) {
+    const serializedItems = value.map((item, index) =>
+      serializeValue(item, `${path}[${index}]`, state)
+    );
+
+    return `[${serializedItems.join(', ')}]`;
+  }
+
+  if (isRecord(value)) {
+    if (state.seen.has(value)) {
+      throw new Error(`${path} contains a circular reference.`);
+    }
+
+    state.seen.add(value);
+
+    const serializedEntries = Object.entries(value)
+      .filter(([, nestedValue]) => nestedValue !== undefined)
+      .map(([key, nestedValue]) => {
+        const serializedNestedValue = serializeValue(nestedValue, `${path}.${key}`, state);
+
+        return `${JSON.stringify(key)}: ${serializedNestedValue}`;
+      });
+
+    return `{ ${serializedEntries.join(', ')} }`;
+  }
+
+  throw new Error(
+    `${path} contains an unsupported value of type ${typeof value}. ` +
+      'Only plain objects, arrays, primitives, and regular expressions are supported.'
+  );
+}
+
+function assertNoFunctions(value: unknown, path: string): void {
+  const state = {
+    seen: new WeakSet<object>()
+  };
+
+  assertNoFunctionsRecursive(value, path, state);
+}
+
+function assertNoFunctionsRecursive(
+  value: unknown,
+  path: string,
+  state: { seen: WeakSet<object> }
+): void {
+  if (typeof value === 'function') {
+    throw new Error(
+      `${path} cannot contain functions. ` +
+        'Function-valued sanitization hooks are not supported in framework options.'
+    );
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => {
+      assertNoFunctionsRecursive(item, `${path}[${index}]`, state);
+    });
+
+    return;
+  }
+
+  if (isRecord(value)) {
+    if (state.seen.has(value)) {
+      return;
+    }
+
+    state.seen.add(value);
+
+    Object.entries(value).forEach(([key, nestedValue]) => {
+      assertNoFunctionsRecursive(nestedValue, `${path}.${key}`, state);
+    });
+  }
+}
+
 function matchSegments(pathSegments: string[], patternSegments: string[]): boolean {
   if (patternSegments.length === 0) {
     return pathSegments.length === 0;

package/src/middleware.ts

@@ -4,8 +4,7 @@ import type { Integration } from './integrations/index.ts';
 import type { SanitizationOptions } from './lib/sanitization.ts';
 import { resolveSanitizationOptions, sanitizeRenderPayload } from './lib/sanitization.ts';
 import { resolveStoryModuleMock, withStoryModuleMocks } from './module-mocks.ts';
-import { applyMswHandlers } from './msw.ts';
-import { selectStoryRules } from './rules.ts';
+import { selectStoryRules, withStoryRuleCleanups } from './rules.ts';
 import type { RenderStoryInput } from './types.ts';
 import { addRenderers, resolveClientModules } from 'virtual:astro-container-renderers';
 
@@ -33,7 +32,6 @@ export type HandlerProps = {
 };
 
 type HandlerFactoryOptions = {
-  mode?: 'development' | 'production';
   sanitization?: SanitizationOptions;
   rulesConfigFilePath?: string;
   resolveRulesConfigModule?: ResolveRulesConfigModule;
@@ -41,7 +39,52 @@ type HandlerFactoryOptions = {
 };
 
 export async function handlerFactory(_integrations: Integration[], options?: HandlerFactoryOptions) {
-  const mode = options?.mode ?? 'development';
+  // Inject a passthrough image service before any component renders.
+  //
+  // AstroContainer has no image service configuration API, and the default
+  // getConfiguredImageService() tries to dynamically import "virtual:image-service"
+  // which fails in astro6/Vite 7's module runner. Even when it succeeds (astro5),
+  // the noop service still routes through /_image?href=... URLs that the Storybook
+  // dev server cannot serve.
+  //
+  // Pre-populating globalThis.astroAsset.imageService bypasses the dynamic import
+  // entirely. Our service returns the direct /@fs/... Vite URL from the ImageMetadata
+  // object, which Vite can serve as a static asset in the browser.
+  if (!globalThis.astroAsset) {
+    (globalThis as Record<string, unknown>).astroAsset = {};
+  }
+  (globalThis.astroAsset as Record<string, unknown>).imageService = {
+    propertiesToHash: ['src'],
+    validateOptions(options: Record<string, unknown>) {
+      return options;
+    },
+    getURL(options: { src: unknown }) {
+      const src = options.src;
+
+      if (src != null && typeof src === 'object' && 'src' in src && typeof (src as Record<string, unknown>).src === 'string') {
+        // ImageMetadata object — return the /@fs/... Vite URL directly
+        return (src as Record<string, unknown>).src as string;
+      }
+
+      return typeof src === 'string' ? src : '';
+    },
+    getHTMLAttributes(options: Record<string, unknown>) {
+      const { src, width, height, format, quality, densities, widths, formats, layout, priority, fit, position, background, ...attrs } = options;
+      const srcObj = src != null && typeof src === 'object' ? src as Record<string, unknown> : null;
+
+      return {
+        ...attrs,
+        width: width ?? srcObj?.width,
+        height: height ?? srcObj?.height,
+        loading: (attrs.loading as string | undefined) ?? 'lazy',
+        decoding: (attrs.decoding as string | undefined) ?? 'async',
+      };
+    },
+    getSrcSet() {
+      return [];
+    }
+  };
+
   const container = await AstroContainer.create({
     // Somewhat hacky way to force client-side Storybook's Vite to resolve modules properly
     resolve: async (specifier) => {
@@ -116,33 +159,32 @@ export async function handlerFactory(_integrations: Integration[], options?: Han
       const selectedRules = await selectStoryRules({
         configModule: rulesConfigModule,
         configFilePath: options?.rulesConfigFilePath,
-        mode,
         story: data.story
       });
 
-      await applyMswHandlers(selectedRules.mswHandlers);
-
-      return withStoryModuleMocks(selectedRules.moduleMocks, async () => {
-        const patchedComponent = await loadPatchedComponent(
-          data.component,
-          selectedRules.moduleMocks.size === 0
-        );
-        const processedArgs = await processImageMetadata(data.args ?? {});
-        const sanitizedPayload = sanitizeRenderPayload(
-          {
-            args: processedArgs,
-            slots: data.slots ?? {}
-          },
-          sanitizationOptions
-        );
-
-        return container.renderToString(
-          patchedComponent as Parameters<typeof container.renderToString>[0],
-          {
-            props: sanitizedPayload.args,
-            slots: sanitizedPayload.slots
-          }
-        );
+      return withStoryRuleCleanups(selectedRules.cleanups, async () => {
+        return withStoryModuleMocks(selectedRules.moduleMocks, async () => {
+          const patchedComponent = await loadPatchedComponent(
+            data.component,
+            selectedRules.moduleMocks.size === 0
+          );
+          const processedArgs = await processImageMetadata(data.args ?? {});
+          const sanitizedPayload = sanitizeRenderPayload(
+            {
+              args: processedArgs,
+              slots: data.slots ?? {}
+            },
+            sanitizationOptions
+          );
+
+          return container.renderToString(
+            patchedComponent as Parameters<typeof container.renderToString>[0],
+            {
+              props: sanitizedPayload.args,
+              slots: sanitizedPayload.slots
+            }
+          );
+        });
       });
     };
 
@@ -194,7 +236,11 @@ async function processImageMetadata(
 
   for (const [key, value] of Object.entries(args)) {
     if (isImageMetadata(value)) {
-      processed[key] = convertImageMetadataToUrl(value);
+      // Keep ImageMetadata as a plain object — Astro's image service checks
+      // isESMImportedImage (typeof src === 'object') and skips the /@fs/ string
+      // validation that throws LocalImageUsedWrongly. Converting to a URL string
+      // causes that error when the string starts with /@fs/.
+      processed[key] = value;
 
       continue;
     }
@@ -203,7 +249,7 @@ async function processImageMetadata(
       processed[key] = await Promise.all(
         value.map(async (item) => {
           if (isImageMetadata(item)) {
-            return convertImageMetadataToUrl(item);
+            return item;
           }
 
           if (isRecord(item)) {
@@ -237,20 +283,6 @@ function isImageMetadata(value: unknown): value is Record<string, unknown> {
   );
 }
 
-function convertImageMetadataToUrl(imageMetadata: Record<string, unknown>): string {
-  const src = imageMetadata.src;
-  const fsPath = imageMetadata.fsPath;
-
-  if (typeof src === 'string') {
-    return src;
-  }
-
-  if (typeof fsPath === 'string') {
-    return fsPath;
-  }
-
-  return String(imageMetadata);
-}
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;

package/src/node/index.ts

@@ -0,0 +1,7 @@
+import type { StorybookConfig } from '../types.ts';
+
+export function defineMain(config: StorybookConfig): StorybookConfig {
+  return config;
+}
+
+export type { StorybookConfig };

package/src/preset.ts

@@ -1,21 +1,30 @@
 import type { StorybookConfigVite, FrameworkOptions } from './types.ts';
 import { vitePluginStorybookAstroMiddleware } from './viteStorybookAstroMiddlewarePlugin.ts';
 import { viteStorybookRendererFallbackPlugin } from './viteStorybookRendererFallbackPlugin.ts';
+import { viteStorybookAstroRendererPlugin } from './viteStorybookAstroRendererPlugin.ts';
 import { vitePluginAstroComponentMarker } from './vitePluginAstroComponentMarker.ts';
 import { vitePluginAstroBuildPrerender } from './vitePluginAstroBuildPrerender.ts';
+import { vitePluginAstroBuildServer } from './vitePluginAstroBuildServer.ts';
+import { vitePluginAstroIntegrationOptsFallback } from './vitePluginAstroIntegrationOptsFallback.ts';
 import { vitePluginAstroVueFallback } from './vitePluginAstroVueFallback.ts';
+import { vitePluginAstroToolbarFallback } from './vitePluginAstroToolbarFallback.ts';
 import { resolveSanitizationOptions } from './lib/sanitization.ts';
 import { mergeWithAstroConfig } from './vitePluginAstro.ts';
 
 export const core = {
   builder: '@storybook/builder-vite',
-  renderer: '@storybook-astro/renderer'
+  // Use import.meta.resolve so Storybook receives an absolute file:// URL
+  // to the renderer preset rather than a bare package specifier.  When
+  // package managers like pnpm use strict node_modules isolation, bare
+  // specifiers are resolved from the *project root*, where the renderer
+  // (a dep of this framework, not the user's project) is not hoisted.
+  // The absolute URL is resolved from *this* file's location where the
+  // renderer is always accessible as a direct dependency.
+  renderer: import.meta.resolve('@storybook-astro/renderer')
 };
 
 export const viteFinal: StorybookConfigVite['viteFinal'] = async (config, { configType, presets }) => {
   const options = await presets.apply<FrameworkOptions>('frameworkOptions');
-  const { vitePlugin: storybookAstroMiddlewarePlugin, viteConfig } =
-    await vitePluginStorybookAstroMiddleware(options);
 
   if (!config.plugins) {
     config.plugins = [];
@@ -23,22 +32,53 @@ export const viteFinal: StorybookConfigVite['viteFinal'] = async (config, { conf
 
   const integrations = options.integrations ?? [];
   const resolveFrom = options.resolveFrom ?? process.cwd();
+  const renderMode = options.renderMode ?? 'server';
   const mode = configType === 'DEVELOPMENT' ? 'development' : 'production';
   const command = configType === 'DEVELOPMENT' ? 'serve' : 'build';
 
   resolveSanitizationOptions(options.sanitization);
 
+  config.envPrefix = mergeEnvPrefixes(config.envPrefix, 'STORYBOOK_');
+
+  const { vitePlugin: storybookAstroMiddlewarePlugin, viteConfig } =
+    await vitePluginStorybookAstroMiddleware(options);
+
   config.plugins.push(
-    storybookAstroMiddlewarePlugin,
     viteStorybookRendererFallbackPlugin(integrations),
+    viteStorybookAstroRendererPlugin({
+      mode,
+      renderMode,
+      server: options.server
+    }),
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     vitePluginAstroComponentMarker() as any,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    vitePluginAstroBuildPrerender(options) as any,
+    vitePluginAstroIntegrationOptsFallback(),
+    vitePluginAstroToolbarFallback(),
     vitePluginAstroVueFallback(),
-    ...viteConfig.plugins
   );
 
+  if (configType === 'DEVELOPMENT') {
+    config.plugins.push(storybookAstroMiddlewarePlugin, ...viteConfig.plugins);
+  } else if (renderMode === 'static') {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    config.plugins.push(vitePluginAstroBuildPrerender(options) as any);
+  } else {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    config.plugins.push(vitePluginAstroBuildServer(options) as any);
+  }
+
+  if (configType !== 'DEVELOPMENT') {
+    config.build = {
+      ...(config.build ?? {}),
+      manifest: true
+    };
+
+    config.build.rollupOptions = {
+      ...(config.build.rollupOptions ?? {}),
+      preserveEntrySignatures: 'strict'
+    };
+  }
+
   // Add React/ReactDOM aliases for storybook-solidjs compatibility
   if (!config.resolve) {
     config.resolve = {};
@@ -59,17 +99,18 @@ export const viteFinal: StorybookConfigVite['viteFinal'] = async (config, { conf
 
   const finalConfig = await mergeWithAstroConfig(config, integrations, resolveFrom, mode, command);
 
-  // Exclude @astrojs/vue from dependency optimization because it imports
-  // virtual modules that esbuild cannot resolve (virtual:@astrojs/vue/app).
-  // This must be done after mergeWithAstroConfig to avoid being overwritten.
+  // Exclude Astro integration packages from dependency optimization because
+  // they import virtual modules that esbuild cannot resolve.
   if (!finalConfig.optimizeDeps) {
     finalConfig.optimizeDeps = {};
   }
   if (!finalConfig.optimizeDeps.exclude) {
     finalConfig.optimizeDeps.exclude = [];
   }
-  if (!finalConfig.optimizeDeps.exclude.includes('@astrojs/vue')) {
-    finalConfig.optimizeDeps.exclude.push('@astrojs/vue');
+  for (const pkg of ['@astrojs/vue', '@astrojs/react', '@astrojs/preact']) {
+    if (!finalConfig.optimizeDeps.exclude.includes(pkg)) {
+      finalConfig.optimizeDeps.exclude.push(pkg);
+    }
   }
   // Exclude the renderer from Vite's esbuild pre-bundler so that
   // import.meta.hot is preserved in the preview iframe. When installed
@@ -80,20 +121,49 @@ export const viteFinal: StorybookConfigVite['viteFinal'] = async (config, { conf
   if (!finalConfig.optimizeDeps.exclude.includes('@storybook-astro/renderer')) {
     finalConfig.optimizeDeps.exclude.push('@storybook-astro/renderer');
   }
-  // Mark Vue virtual modules as external so esbuild doesn't try to resolve them
+  // 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.
+  const integrationVirtualModules = [
+    'virtual:@astrojs/vue/app',
+    'virtual:astro:vue-app',
+    'astro:react:opts',
+    'astro:preact:opts',
+    'astro:toolbar:internal'
+  ];
+
+  // Vite ≤7 (esbuild-based optimizer)
   if (!finalConfig.optimizeDeps.esbuildOptions) {
     finalConfig.optimizeDeps.esbuildOptions = {};
   }
   if (!finalConfig.optimizeDeps.esbuildOptions.external) {
     finalConfig.optimizeDeps.esbuildOptions.external = [];
   }
-  const vueVirtualModules = ['virtual:@astrojs/vue/app', 'virtual:astro:vue-app'];
-
-  for (const mod of vueVirtualModules) {
+  for (const mod of integrationVirtualModules) {
     if (!finalConfig.optimizeDeps.esbuildOptions.external.includes(mod)) {
       finalConfig.optimizeDeps.esbuildOptions.external.push(mod);
     }
   }
 
+  // Vite 8+ (Rolldown-based optimizer) — same semantics, different key
+  // Use a loose cast because rolldownOptions is absent from Vite <8 types.
+  const optimizeDepsMut = finalConfig.optimizeDeps as Record<string, unknown>;
+  const rolldownOpts = (optimizeDepsMut.rolldownOptions ?? {}) as { external?: string[] };
+
+  rolldownOpts.external = Array.from(
+    new Set([...(rolldownOpts.external ?? []), ...integrationVirtualModules])
+  );
+  optimizeDepsMut.rolldownOptions = rolldownOpts;
+
   return finalConfig;
 };
+
+function mergeEnvPrefixes(
+  existing: string | string[] | undefined,
+  additionalPrefix: string
+): string[] {
+  const prefixes = Array.isArray(existing) ? existing : existing ? [existing] : [];
+
+  return Array.from(new Set([...prefixes, additionalPrefix]));
+}

package/src/renderer/renderer-dev.ts

@@ -0,0 +1,82 @@
+import type {
+  RenderComponentInput,
+  RenderPromise,
+  RenderResponseMessage
+} from '@storybook-astro/renderer/types';
+
+const pendingMessages = new Map<string, RenderPromise>();
+const ASTRO_SERVER_UNAVAILABLE_ERROR_NAME = 'AstroRenderServerUnavailableError';
+
+export async function render(data: RenderComponentInput, timeoutMs = 5000) {
+  // eslint-disable-next-line n/no-unsupported-features/node-builtins
+  const id = crypto.randomUUID();
+
+  const promise = new Promise<RenderResponseMessage['data']>((resolve, reject) => {
+    const timeoutId = setTimeout(() => {
+      pendingMessages.delete(id);
+
+      const error = new Error(
+        `Unable to reach Astro rendering server. No render response was received within ${timeoutMs}ms.`
+      );
+
+      error.name = ASTRO_SERVER_UNAVAILABLE_ERROR_NAME;
+
+      reject(error);
+    }, timeoutMs);
+
+    pendingMessages.set(id, { resolve, reject, timeoutId });
+  });
+
+  import.meta.hot?.send('astro:render:request', {
+    ...data,
+    id
+  });
+
+  return promise;
+}
+
+export function init() {
+  import.meta.hot?.on('vite:afterUpdate', (payload) => {
+    if (payload.updates.some((update) => isAstroStyleUpdate(update.path))) {
+      applyStyles();
+    }
+  });
+
+  import.meta.hot?.on('astro:render:response', (data: RenderResponseMessage['data']) => {
+    if (!data.id || !pendingMessages.has(data.id)) {
+      return;
+    }
+
+    const pendingMessage = pendingMessages.get(data.id);
+
+    if (!pendingMessage) {
+      return;
+    }
+
+    clearTimeout(pendingMessage.timeoutId);
+    pendingMessages.delete(data.id);
+    pendingMessage.resolve(data);
+  });
+}
+
+export function applyStyles() {
+  Array.from(document.querySelectorAll('style[data-vite-dev-id]'))
+    .filter((element) => /__vite__updateStyle/.test(element.innerHTML))
+    .forEach((element) => {
+      const script = document.createElement('script');
+
+      script.type = 'module';
+
+      const safeScriptContent = element.innerHTML
+        .replaceAll('import.meta.hot.accept(', 'import.meta.hot?.accept(')
+        .replaceAll('import.meta.hot.prune(', 'import.meta.hot?.prune(');
+
+      script.appendChild(document.createTextNode(safeScriptContent));
+      document.head.appendChild(script);
+      document.head.removeChild(script);
+    });
+}
+
+function isAstroStyleUpdate(path: string): boolean {
+  return /\.astro\?astro&type=style&index=\d+&lang\.(css|scss|sass|less|stylus)$/.test(path);
+}

package/src/renderer/renderer-server.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import { createServerRenderer } from './renderer-server.ts';
+
+const renderPayload = {
+  component: '/src/components/Button.astro',
+  args: { label: 'Click' },
+  slots: {},
+  story: undefined
+};
+
+describe('createServerRenderer', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  test('sends bearer auth header with default authorization header', async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      text: async () => '<div>rendered</div>'
+    }));
+
+    vi.stubGlobal('fetch', fetchMock);
+    vi.stubGlobal('crypto', { randomUUID: () => 'uuid-1' });
+
+    const renderer = createServerRenderer({
+      serverUrl: 'http://localhost:4000',
+      authToken: 'secret'
+    });
+
+    await expect(renderer.render(renderPayload, 1000)).resolves.toEqual({
+      id: 'uuid-1',
+      html: '<div>rendered</div>'
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock).toHaveBeenCalledWith(
+      'http://localhost:4000/render',
+      expect.objectContaining({
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          authorization: 'Bearer secret'
+        }
+      })
+    );
+  });
+
+  test('uses custom auth header without bearer prefix', async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      text: async () => '<div>ok</div>'
+    }));
+
+    vi.stubGlobal('fetch', fetchMock);
+    vi.stubGlobal('crypto', { randomUUID: () => 'uuid-2' });
+
+    const renderer = createServerRenderer({
+      serverUrl: 'http://localhost:5000',
+      authToken: 'token-123',
+      authHeader: 'x-storybook-token'
+    });
+
+    await renderer.render(renderPayload, 1000);
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'http://localhost:5000/render',
+      expect.objectContaining({
+        headers: {
+          'content-type': 'application/json',
+          'x-storybook-token': 'token-123'
+        }
+      })
+    );
+  });
+
+  test('throws a clear error when server rejects auth', async () => {
+    vi.stubGlobal('fetch',
+      vi.fn(async () => ({
+        ok: false,
+        status: 401,
+        statusText: 'Unauthorized',
+        text: async () => ''
+      }))
+    );
+    vi.stubGlobal('crypto', { randomUUID: () => 'uuid-3' });
+
+    const renderer = createServerRenderer({
+      serverUrl: 'http://localhost:6000',
+      authToken: 'wrong'
+    });
+
+    await expect(renderer.render(renderPayload, 1000)).rejects.toThrow(
+      'Astro rendering server rejected the request with 401.'
+    );
+  });
+});