@storybook-astro/framework 1.2.0 → 1.3.0-canary.1

package/src/astroRenderHandler.ts

@@ -0,0 +1,203 @@
+import type { experimental_AstroContainer as AstroContainer } from 'astro/container';
+import type { SanitizationOptions } from './lib/sanitization.ts';
+import { resolveSanitizationOptions, sanitizeRenderPayload } from './lib/sanitization.ts';
+import { runWithStoryRules, type ResolveRulesConfigModule } from './storyRulesRuntime.ts';
+import type { RenderStoryInput } from './types.ts';
+
+type AstroCreateResult = {
+  createAstro?: (...args: unknown[]) => unknown;
+};
+
+type AstroComponentFactory = ((
+  result: AstroCreateResult,
+  props: unknown,
+  slots: unknown
+) => unknown) & {
+  isAstroComponentFactory?: boolean;
+  moduleId?: string;
+  propagation?: unknown;
+};
+
+export type HandlerProps = {
+  component: string;
+  args?: Record<string, unknown>;
+  slots?: Record<string, unknown>;
+  story?: RenderStoryInput;
+};
+
+type CreateAstroRenderHandlerOptions = {
+  container: Awaited<ReturnType<typeof AstroContainer.create>>;
+  sanitization?: SanitizationOptions;
+  rulesConfigFilePath?: string;
+  resolveRulesConfigModule?: ResolveRulesConfigModule;
+  loadModule: (id: string) => Promise<{ default: unknown }>;
+  invalidateModuleGraph?: () => void;
+};
+
+export function createAstroRenderHandler(options: CreateAstroRenderHandlerOptions) {
+  const sanitizationOptions = resolveSanitizationOptions(options.sanitization);
+  const componentCache = new Map<string, Promise<AstroComponentFactory>>();
+  let renderQueue = Promise.resolve<void>(undefined);
+
+  async function loadPatchedComponent(componentId: string, useCache = true) {
+    if (!useCache) {
+      const { default: component } = await options.loadModule(componentId);
+
+      return patchCreateAstroCompat(component);
+    }
+
+    if (!componentCache.has(componentId)) {
+      componentCache.set(
+        componentId,
+        (async () => {
+          const { default: component } = await options.loadModule(componentId);
+
+          return patchCreateAstroCompat(component);
+        })()
+      );
+    }
+
+    const cachedComponent = componentCache.get(componentId);
+
+    if (!cachedComponent) {
+      throw new Error(`Failed to load Astro component: ${componentId}`);
+    }
+
+    try {
+      return await cachedComponent;
+    } catch (error) {
+      componentCache.delete(componentId);
+      throw error;
+    }
+  }
+
+  return async function handler(data: HandlerProps) {
+    const executeRender = async () => {
+      return runWithStoryRules(
+        {
+          story: data.story,
+          rulesConfigFilePath: options.rulesConfigFilePath,
+          resolveRulesConfigModule: options.resolveRulesConfigModule,
+          invalidateModuleGraph: options.invalidateModuleGraph
+        },
+        async (selectedRules) => {
+          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 options.container.renderToString(
+            patchedComponent as Parameters<typeof options.container.renderToString>[0],
+            {
+              props: sanitizedPayload.args,
+              slots: sanitizedPayload.slots
+            }
+          );
+        }
+      );
+    };
+
+    const resultPromise = renderQueue.then(executeRender, executeRender);
+
+    renderQueue = resultPromise.then(
+      () => undefined,
+      () => undefined
+    );
+
+    return resultPromise;
+  };
+}
+
+export function patchCreateAstroCompat(component: unknown): AstroComponentFactory {
+  if (typeof component !== 'function') {
+    throw new Error('Expected Astro component factory to be a function.');
+  }
+
+  const originalComponent = component as AstroComponentFactory;
+  const wrapped = ((result: AstroCreateResult, props: unknown, slots: unknown) => {
+    if (result && typeof result.createAstro === 'function') {
+      const originalCreateAstro = result.createAstro;
+      const runtimeExpectsAstroGlobal = originalCreateAstro.length >= 3;
+
+      result.createAstro = (...args: unknown[]) => {
+        if (args.length === 3 && !runtimeExpectsAstroGlobal) {
+          return originalCreateAstro(args[1], args[2]);
+        }
+
+        return originalCreateAstro(...args);
+      };
+    }
+
+    return originalComponent(result, props, slots);
+  }) as AstroComponentFactory;
+
+  wrapped.isAstroComponentFactory = originalComponent.isAstroComponentFactory;
+  wrapped.moduleId = originalComponent.moduleId;
+  wrapped.propagation = originalComponent.propagation;
+
+  return wrapped;
+}
+
+async function processImageMetadata(
+  args: Record<string, unknown>
+): Promise<Record<string, unknown>> {
+  const processed: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(args)) {
+    if (isImageMetadata(value)) {
+      // Keep ImageMetadata as an object so Astro's image pipeline still
+      // recognizes it as an imported image and skips local path validation.
+      processed[key] = value;
+
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      processed[key] = await Promise.all(
+        value.map(async (item) => {
+          if (isImageMetadata(item)) {
+            return item;
+          }
+
+          if (isRecord(item)) {
+            return processImageMetadata(item);
+          }
+
+          return item;
+        })
+      );
+
+      continue;
+    }
+
+    if (isRecord(value)) {
+      processed[key] = await processImageMetadata(value);
+
+      continue;
+    }
+
+    processed[key] = value;
+  }
+
+  return processed;
+}
+
+function isImageMetadata(value: unknown): value is Record<string, unknown> {
+  return (
+    isRecord(value) &&
+    typeof value.src === 'string' &&
+    ('width' in value || 'height' in value || 'format' in value)
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/src/importAstroConfig.ts

@@ -7,5 +7,5 @@ export async function importAstroConfig(resolveFrom: string) {
     paths: [resolveFrom]
   });
 
-  return import(pathToFileURL(astroConfigEntrypoint).href);
+  return import(/* @vite-ignore */ pathToFileURL(astroConfigEntrypoint).href);
 }

package/src/index.ts

@@ -44,6 +44,8 @@ export type {
 } from './types.ts';
 export type {
   StoryRuleCleanup,
+  StoryRuleMock,
+  StoryRuleMockFactory,
   StoryRule,
   StoryRulesConfig,
   StoryRuleSelection,

package/src/integrations/alpine.ts

@@ -5,6 +5,7 @@ export type Options = Record<string, unknown>;
 
 export class AlpineIntegration implements Integration {
   readonly name = 'alpine';
+  readonly factoryName = 'alpinejs';
   readonly dependencies = [
     '@astrojs/alpinejs',
     'alpinejs'

package/src/integrations/base.ts

@@ -13,6 +13,12 @@ export type RendererDeclaration = {
 
 export abstract class Integration {
   abstract readonly name: string;
+  // Identifier used to import this integration's factory from
+  // `@storybook-astro/framework/integrations` when generating the server
+  // runtime module. Defaults to `name` for integrations whose public name
+  // matches their factory export. Override when they diverge (e.g. Alpine's
+  // `name` is "alpine" but its factory export is `alpinejs`).
+  readonly factoryName?: string;
   abstract readonly dependencies: string[];
   abstract readonly options: Record<string | number | symbol, unknown>;
   abstract readonly renderer: RendererDeclaration;

package/src/middleware.ts

@@ -1,51 +1,34 @@
+/// <reference path="./virtual.d.ts" />
+
 import { pathToFileURL } from 'node:url';
 import { experimental_AstroContainer as AstroContainer } from 'astro/container';
+import { ensureAstroPassthroughImageService } from './astroImageService.ts';
+import { createAstroRenderHandler, type HandlerProps } from './astroRenderHandler.ts';
 import type { Integration } from './integrations/index.ts';
-import { installPassthroughImageService } from './lib/passthrough-image-service.ts';
 import type { SanitizationOptions } from './lib/sanitization.ts';
-import { resolveSanitizationOptions, sanitizeRenderPayload } from './lib/sanitization.ts';
-import { resolveStoryModuleMock, withStoryModuleMocks } from './module-mocks.ts';
-import { selectStoryRules, withStoryRuleCleanups } from './rules.ts';
-import type { RenderStoryInput } from './types.ts';
+import { resolveStoryModuleMock } from './module-mocks.ts';
 import { addRenderers, resolveClientModules } from 'virtual:astro-container-renderers';
 
 type ResolveRulesConfigModule = () => unknown | Promise<unknown>;
 
-type AstroCreateResult = {
-  createAstro?: (...args: unknown[]) => unknown;
-};
-
-type AstroComponentFactory = ((
-  result: AstroCreateResult,
-  props: unknown,
-  slots: unknown
-) => unknown) & {
-  isAstroComponentFactory?: boolean;
-  moduleId?: string;
-  propagation?: unknown;
-};
-
-export type HandlerProps = {
-  component: string;
-  args?: Record<string, unknown>;
-  slots?: Record<string, unknown>;
-  story?: RenderStoryInput;
-};
-
 type HandlerFactoryOptions = {
   sanitization?: SanitizationOptions;
   rulesConfigFilePath?: string;
   resolveRulesConfigModule?: ResolveRulesConfigModule;
   loadModule?: (id: string) => Promise<{ default: unknown }>;
+  invalidateModuleGraph?: () => void;
+  resolveModule?: (specifier: string) => string | undefined;
 };
 
-export async function handlerFactory(_integrations: Integration[], options?: HandlerFactoryOptions) {
-  // Inject a passthrough image service before any component renders. See
-  // `lib/passthrough-image-service.ts` for why this is necessary.
-  installPassthroughImageService();
+export type { HandlerProps };
+
+export async function handlerFactory(
+  _integrations: Integration[],
+  options?: HandlerFactoryOptions
+) {
+  ensureAstroPassthroughImageService();
 
   const container = await AstroContainer.create({
-    // Somewhat hacky way to force client-side Storybook's Vite to resolve modules properly
     resolve: async (specifier) => {
       const mockedModule = resolveStoryModuleMock(specifier);
 
@@ -53,6 +36,12 @@ export async function handlerFactory(_integrations: Integration[], options?: Han
         return mockedModule;
       }
 
+      const customResolution = options?.resolveModule?.(specifier);
+
+      if (customResolution) {
+        return customResolution;
+      }
+
       if (specifier.startsWith('astro:scripts')) {
         return `/@id/${specifier}`;
       }
@@ -68,7 +57,7 @@ export async function handlerFactory(_integrations: Integration[], options?: Han
   });
 
   addRenderers(container);
-  const sanitizationOptions = resolveSanitizationOptions(options?.sanitization);
+
   const loadModule =
     options?.loadModule ??
     ((id: string) => {
@@ -76,173 +65,13 @@ export async function handlerFactory(_integrations: Integration[], options?: Han
 
       return import(/* @vite-ignore */ normalizedId);
     });
-  const componentCache = new Map<string, Promise<AstroComponentFactory>>();
-  let renderQueue = Promise.resolve<void>(undefined);
-
-  async function loadPatchedComponent(componentId: string, useCache = true) {
-    if (!useCache) {
-      const { default: component } = await loadModule(componentId);
-
-      return patchCreateAstroCompat(component);
-    }
-
-    if (!componentCache.has(componentId)) {
-      componentCache.set(componentId, (async () => {
-        const { default: component } = await loadModule(componentId);
-
-        return patchCreateAstroCompat(component);
-      })());
-    }
-
-    const cachedComponent = componentCache.get(componentId);
-
-    if (!cachedComponent) {
-      throw new Error(`Failed to load Astro component: ${componentId}`);
-    }
-
-    try {
-      return await cachedComponent;
-    } catch (error) {
-      // Drop failed entries so transient/module errors can recover on the next request.
-      componentCache.delete(componentId);
-      throw error;
-    }
-  }
-
-  return async function handler(data: HandlerProps) {
-    const executeRender = async () => {
-      const rulesConfigModule = options?.resolveRulesConfigModule
-        ? await options.resolveRulesConfigModule()
-        : undefined;
-
-      const selectedRules = await selectStoryRules({
-        configModule: rulesConfigModule,
-        configFilePath: options?.rulesConfigFilePath,
-        story: data.story
-      });
-
-      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
-            }
-          );
-        });
-      });
-    };
-
-    const resultPromise = renderQueue.then(executeRender, executeRender);
-
-    renderQueue = resultPromise.then(
-      () => undefined,
-      () => undefined
-    );
-
-    return resultPromise;
-  };
-}
-
-function patchCreateAstroCompat(component: unknown): AstroComponentFactory {
-  if (typeof component !== 'function') {
-    throw new Error('Expected Astro component factory to be a function.');
-  }
-
-  const originalComponent = component as AstroComponentFactory;
-  const wrapped = ((result: AstroCreateResult, props: unknown, slots: unknown) => {
-    if (result && typeof result.createAstro === 'function') {
-      const originalCreateAstro = result.createAstro;
-      const runtimeExpectsAstroGlobal = originalCreateAstro.length >= 3;
 
-      result.createAstro = (...args: unknown[]) => {
-        if (args.length === 3 && !runtimeExpectsAstroGlobal) {
-          return originalCreateAstro(args[1], args[2]);
-        }
-
-        return originalCreateAstro(...args);
-      };
-    }
-
-    return originalComponent(result, props, slots);
-  }) as AstroComponentFactory;
-
-  wrapped.isAstroComponentFactory = originalComponent.isAstroComponentFactory;
-  wrapped.moduleId = originalComponent.moduleId;
-  wrapped.propagation = originalComponent.propagation;
-
-  return wrapped;
-}
-
-async function processImageMetadata(
-  args: Record<string, unknown>
-): Promise<Record<string, unknown>> {
-  const processed: Record<string, unknown> = {};
-
-  for (const [key, value] of Object.entries(args)) {
-    if (isImageMetadata(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;
-    }
-
-    if (Array.isArray(value)) {
-      processed[key] = await Promise.all(
-        value.map(async (item) => {
-          if (isImageMetadata(item)) {
-            return item;
-          }
-
-          if (isRecord(item)) {
-            return processImageMetadata(item);
-          }
-
-          return item;
-        })
-      );
-
-      continue;
-    }
-
-    if (isRecord(value)) {
-      processed[key] = await processImageMetadata(value);
-
-      continue;
-    }
-
-    processed[key] = value;
-  }
-
-  return processed;
-}
-
-function isImageMetadata(value: unknown): value is Record<string, unknown> {
-  return (
-    isRecord(value) &&
-    typeof value.src === 'string' &&
-    ('width' in value || 'height' in value || 'format' in value)
-  );
-}
-
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null;
+  return createAstroRenderHandler({
+    container,
+    sanitization: options?.sanitization,
+    rulesConfigFilePath: options?.rulesConfigFilePath,
+    resolveRulesConfigModule: options?.resolveRulesConfigModule,
+    loadModule,
+    invalidateModuleGraph: options?.invalidateModuleGraph
+  });
 }

package/src/module-mocks.ts

@@ -1,16 +1,164 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
+const STORYBOOK_ASTRO_GET_MOCK_EXPORT = '__STORYBOOK_ASTRO_GET_STORY_MODULE_MOCK_EXPORT__';
 
-export type StoryModuleMocks = Map<string, string>;
+export const STORYBOOK_ASTRO_INLINE_MODULE_PREFIX = 'virtual:storybook-astro-inline-module:';
 
-const moduleMockStorage = new AsyncLocalStorage<StoryModuleMocks>();
+export type StoryModuleMockEntry = {
+  replacement: string;
+  inlineModuleId?: string;
+};
+
+export type StoryModuleMockFactoryResult = Record<string, unknown>;
+
+export type StoryModuleMocks = Map<string, StoryModuleMockEntry>;
+
+type StoryModuleMocksGlobal = typeof globalThis & {
+  __STORYBOOK_ASTRO_STORY_MODULE_MOCK_STATE__?: {
+    activeModuleMocksStack: StoryModuleMocks[];
+    inlineModuleExports: Map<string, StoryModuleMockFactoryResult>;
+    inlineModuleSequence: number;
+  };
+  __STORYBOOK_ASTRO_GET_STORY_MODULE_MOCK_EXPORT__?: (moduleId: string, exportName: string) => unknown;
+};
+
+const moduleMocksGlobal = globalThis as StoryModuleMocksGlobal;
+
+const moduleMockState =
+  moduleMocksGlobal.__STORYBOOK_ASTRO_STORY_MODULE_MOCK_STATE__ ??
+  (moduleMocksGlobal.__STORYBOOK_ASTRO_STORY_MODULE_MOCK_STATE__ = {
+    activeModuleMocksStack: [],
+    inlineModuleExports: new Map<string, StoryModuleMockFactoryResult>(),
+    inlineModuleSequence: 0
+  });
+
+if (typeof moduleMocksGlobal[STORYBOOK_ASTRO_GET_MOCK_EXPORT] !== 'function') {
+  moduleMocksGlobal[STORYBOOK_ASTRO_GET_MOCK_EXPORT] = getStoryModuleMockExport;
+}
 
 export async function withStoryModuleMocks<T>(
   moduleMocks: StoryModuleMocks,
   callback: () => Promise<T>
 ): Promise<T> {
-  return moduleMockStorage.run(moduleMocks, callback);
+  moduleMockState.activeModuleMocksStack.push(moduleMocks);
+
+  try {
+    return await callback();
+  } finally {
+    moduleMockState.activeModuleMocksStack.pop();
+    cleanupInlineModuleMocks(moduleMocks);
+  }
 }
 
 export function resolveStoryModuleMock(specifier: string): string | undefined {
-  return moduleMockStorage.getStore()?.get(specifier);
+  return getActiveModuleMocks()?.get(specifier)?.replacement;
+}
+
+export function createPathStoryModuleMock(replacement: string): StoryModuleMockEntry {
+  return {
+    replacement
+  };
+}
+
+export function createInlineStoryModuleMock(
+  exportsObject: StoryModuleMockFactoryResult
+): StoryModuleMockEntry {
+  const inlineModuleId = `storybook-astro-inline-module:${moduleMockState.inlineModuleSequence}`;
+
+  moduleMockState.inlineModuleSequence += 1;
+  moduleMockState.inlineModuleExports.set(inlineModuleId, exportsObject);
+
+  return {
+    replacement: `${STORYBOOK_ASTRO_INLINE_MODULE_PREFIX}${inlineModuleId}`,
+    inlineModuleId
+  };
+}
+
+export function loadStoryInlineModule(resolvedId: string): string | undefined {
+  const inlineModuleId = normalizeInlineModuleId(resolvedId);
+
+  if (!inlineModuleId) {
+    return undefined;
+  }
+
+  const exportsObject = moduleMockState.inlineModuleExports.get(inlineModuleId);
+
+  if (!exportsObject) {
+    return undefined;
+  }
+
+  return createInlineModuleSource(inlineModuleId, exportsObject);
+}
+
+function cleanupInlineModuleMocks(moduleMocks: StoryModuleMocks) {
+  for (const mockEntry of moduleMocks.values()) {
+    if (mockEntry.inlineModuleId) {
+      moduleMockState.inlineModuleExports.delete(mockEntry.inlineModuleId);
+    }
+  }
+}
+
+function getActiveModuleMocks(): StoryModuleMocks | undefined {
+  return moduleMockState.activeModuleMocksStack[moduleMockState.activeModuleMocksStack.length - 1];
+}
+
+function getStoryModuleMockExport(moduleId: string, exportName: string): unknown {
+  const exportsObject = moduleMockState.inlineModuleExports.get(moduleId);
+
+  if (!exportsObject) {
+    throw new Error(`Inline story module mock is unavailable: ${moduleId}`);
+  }
+
+  return exportsObject[exportName];
+}
+
+function createInlineModuleSource(
+  inlineModuleId: string,
+  exportsObject: StoryModuleMockFactoryResult
+): string {
+  const exportNames = Object.keys(exportsObject);
+  const sourceLines = [
+    `const getStoryModuleMockExport = globalThis.${STORYBOOK_ASTRO_GET_MOCK_EXPORT};`,
+    "if (typeof getStoryModuleMockExport !== 'function') {",
+    "  throw new Error('Inline story module mock helper is unavailable.');",
+    '}',
+    ''
+  ];
+
+  if (Object.prototype.hasOwnProperty.call(exportsObject, 'default')) {
+    sourceLines.push(
+      `export default getStoryModuleMockExport(${JSON.stringify(inlineModuleId)}, 'default');`
+    );
+  }
+
+  for (const exportName of exportNames) {
+    if (exportName === 'default') {
+      continue;
+    }
+
+    assertValidExportName(exportName);
+    sourceLines.push(
+      `export const ${exportName} = getStoryModuleMockExport(${JSON.stringify(inlineModuleId)}, ${JSON.stringify(exportName)});`
+    );
+  }
+
+  if (sourceLines[sourceLines.length - 1] === '') {
+    sourceLines.push('export {};');
+  }
+
+  return sourceLines.join('\n');
+}
+
+function assertValidExportName(exportName: string) {
+  if (!/^[$A-Z_a-z][$\w]*$/u.test(exportName)) {
+    throw new Error(`Story module mock export name is invalid: ${exportName}`);
+  }
+}
+
+function normalizeInlineModuleId(resolvedId: string): string | undefined {
+  const normalizedId = resolvedId.startsWith('\0') ? resolvedId.slice(1) : resolvedId;
+
+  if (!normalizedId.startsWith(STORYBOOK_ASTRO_INLINE_MODULE_PREFIX)) {
+    return undefined;
+  }
+
+  return normalizedId.slice(STORYBOOK_ASTRO_INLINE_MODULE_PREFIX.length);
 }