@storybook-astro/framework 1.1.1 → 1.2.0

package/dist/middleware.js

@@ -1,11 +1,12 @@
 import {
+  installPassthroughImageService,
   resolveSanitizationOptions,
   resolveStoryModuleMock,
   sanitizeRenderPayload,
   selectStoryRules,
   withStoryModuleMocks,
   withStoryRuleCleanups
-} from "./chunk-V76WSNSP.js";
+} from "./chunk-OUEDTRBO.js";
 import "./chunk-G3PMV62Z.js";
 
 // src/middleware.ts
@@ -13,36 +14,7 @@ import { pathToFileURL } from "url";
 import { experimental_AstroContainer as AstroContainer } from "astro/container";
 import { addRenderers, resolveClientModules } from "virtual:astro-container-renderers";
 async function handlerFactory(_integrations, options) {
-  if (!globalThis.astroAsset) {
-    globalThis.astroAsset = {};
-  }
-  globalThis.astroAsset.imageService = {
-    propertiesToHash: ["src"],
-    validateOptions(options2) {
-      return options2;
-    },
-    getURL(options2) {
-      const src = options2.src;
-      if (src != null && typeof src === "object" && "src" in src && typeof src.src === "string") {
-        return src.src;
-      }
-      return typeof src === "string" ? src : "";
-    },
-    getHTMLAttributes(options2) {
-      const { src, width, height, format, quality, densities, widths, formats, layout, priority, fit, position, background, ...attrs } = options2;
-      const srcObj = src != null && typeof src === "object" ? src : null;
-      return {
-        ...attrs,
-        width: width ?? srcObj?.width,
-        height: height ?? srcObj?.height,
-        loading: attrs.loading ?? "lazy",
-        decoding: attrs.decoding ?? "async"
-      };
-    },
-    getSrcSet() {
-      return [];
-    }
-  };
+  installPassthroughImageService();
   const container = await AstroContainer.create({
     // Somewhat hacky way to force client-side Storybook's Vite to resolve modules properly
     resolve: async (specifier) => {

package/dist/middleware.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/middleware.ts"],"sourcesContent":["import { pathToFileURL } from 'node:url';\nimport { experimental_AstroContainer as AstroContainer } from 'astro/container';\nimport type { Integration } from './integrations/index.ts';\nimport type { SanitizationOptions } from './lib/sanitization.ts';\nimport { resolveSanitizationOptions, sanitizeRenderPayload } from './lib/sanitization.ts';\nimport { resolveStoryModuleMock, withStoryModuleMocks } from './module-mocks.ts';\nimport { selectStoryRules, withStoryRuleCleanups } from './rules.ts';\nimport type { RenderStoryInput } from './types.ts';\nimport { addRenderers, resolveClientModules } from 'virtual:astro-container-renderers';\n\ntype ResolveRulesConfigModule = () => unknown | Promise<unknown>;\n\ntype AstroCreateResult = {\n  createAstro?: (...args: unknown[]) => unknown;\n};\n\ntype AstroComponentFactory = ((\n  result: AstroCreateResult,\n  props: unknown,\n  slots: unknown\n) => unknown) & {\n  isAstroComponentFactory?: boolean;\n  moduleId?: string;\n  propagation?: unknown;\n};\n\nexport type HandlerProps = {\n  component: string;\n  args?: Record<string, unknown>;\n  slots?: Record<string, unknown>;\n  story?: RenderStoryInput;\n};\n\ntype HandlerFactoryOptions = {\n  sanitization?: SanitizationOptions;\n  rulesConfigFilePath?: string;\n  resolveRulesConfigModule?: ResolveRulesConfigModule;\n  loadModule?: (id: string) => Promise<{ default: unknown }>;\n};\n\nexport async function handlerFactory(_integrations: Integration[], options?: HandlerFactoryOptions) {\n  // Inject a passthrough image service before any component renders.\n  //\n  // AstroContainer has no image service configuration API, and the default\n  // getConfiguredImageService() tries to dynamically import \"virtual:image-service\"\n  // which fails in astro6/Vite 7's module runner. Even when it succeeds (astro5),\n  // the noop service still routes through /_image?href=... URLs that the Storybook\n  // dev server cannot serve.\n  //\n  // Pre-populating globalThis.astroAsset.imageService bypasses the dynamic import\n  // entirely. Our service returns the direct /@fs/... Vite URL from the ImageMetadata\n  // object, which Vite can serve as a static asset in the browser.\n  if (!globalThis.astroAsset) {\n    (globalThis as Record<string, unknown>).astroAsset = {};\n  }\n  (globalThis.astroAsset as Record<string, unknown>).imageService = {\n    propertiesToHash: ['src'],\n    validateOptions(options: Record<string, unknown>) {\n      return options;\n    },\n    getURL(options: { src: unknown }) {\n      const src = options.src;\n\n      if (src != null && typeof src === 'object' && 'src' in src && typeof (src as Record<string, unknown>).src === 'string') {\n        // ImageMetadata object — return the /@fs/... Vite URL directly\n        return (src as Record<string, unknown>).src as string;\n      }\n\n      return typeof src === 'string' ? src : '';\n    },\n    getHTMLAttributes(options: Record<string, unknown>) {\n      const { src, width, height, format, quality, densities, widths, formats, layout, priority, fit, position, background, ...attrs } = options;\n      const srcObj = src != null && typeof src === 'object' ? src as Record<string, unknown> : null;\n\n      return {\n        ...attrs,\n        width: width ?? srcObj?.width,\n        height: height ?? srcObj?.height,\n        loading: (attrs.loading as string | undefined) ?? 'lazy',\n        decoding: (attrs.decoding as string | undefined) ?? 'async',\n      };\n    },\n    getSrcSet() {\n      return [];\n    }\n  };\n\n  const container = await AstroContainer.create({\n    // Somewhat hacky way to force client-side Storybook's Vite to resolve modules properly\n    resolve: async (specifier) => {\n      const mockedModule = resolveStoryModuleMock(specifier);\n\n      if (mockedModule) {\n        return mockedModule;\n      }\n\n      if (specifier.startsWith('astro:scripts')) {\n        return `/@id/${specifier}`;\n      }\n\n      const resolution = resolveClientModules(specifier);\n\n      if (resolution) {\n        return resolution;\n      }\n\n      return specifier;\n    }\n  });\n\n  addRenderers(container);\n  const sanitizationOptions = resolveSanitizationOptions(options?.sanitization);\n  const loadModule =\n    options?.loadModule ??\n    ((id: string) => {\n      const normalizedId = /^[a-zA-Z]:[/\\\\]/.test(id) ? pathToFileURL(id).href : id;\n\n      return import(/* @vite-ignore */ normalizedId);\n    });\n  const componentCache = new Map<string, Promise<AstroComponentFactory>>();\n  let renderQueue = Promise.resolve<void>(undefined);\n\n  async function loadPatchedComponent(componentId: string, useCache = true) {\n    if (!useCache) {\n      const { default: component } = await loadModule(componentId);\n\n      return patchCreateAstroCompat(component);\n    }\n\n    if (!componentCache.has(componentId)) {\n      componentCache.set(componentId, (async () => {\n        const { default: component } = await loadModule(componentId);\n\n        return patchCreateAstroCompat(component);\n      })());\n    }\n\n    const cachedComponent = componentCache.get(componentId);\n\n    if (!cachedComponent) {\n      throw new Error(`Failed to load Astro component: ${componentId}`);\n    }\n\n    try {\n      return await cachedComponent;\n    } catch (error) {\n      // Drop failed entries so transient/module errors can recover on the next request.\n      componentCache.delete(componentId);\n      throw error;\n    }\n  }\n\n  return async function handler(data: HandlerProps) {\n    const executeRender = async () => {\n      const rulesConfigModule = options?.resolveRulesConfigModule\n        ? await options.resolveRulesConfigModule()\n        : undefined;\n\n      const selectedRules = await selectStoryRules({\n        configModule: rulesConfigModule,\n        configFilePath: options?.rulesConfigFilePath,\n        story: data.story\n      });\n\n      return withStoryRuleCleanups(selectedRules.cleanups, async () => {\n        return withStoryModuleMocks(selectedRules.moduleMocks, async () => {\n          const patchedComponent = await loadPatchedComponent(\n            data.component,\n            selectedRules.moduleMocks.size === 0\n          );\n          const processedArgs = await processImageMetadata(data.args ?? {});\n          const sanitizedPayload = sanitizeRenderPayload(\n            {\n              args: processedArgs,\n              slots: data.slots ?? {}\n            },\n            sanitizationOptions\n          );\n\n          return container.renderToString(\n            patchedComponent as Parameters<typeof container.renderToString>[0],\n            {\n              props: sanitizedPayload.args,\n              slots: sanitizedPayload.slots\n            }\n          );\n        });\n      });\n    };\n\n    const resultPromise = renderQueue.then(executeRender, executeRender);\n\n    renderQueue = resultPromise.then(\n      () => undefined,\n      () => undefined\n    );\n\n    return resultPromise;\n  };\n}\n\nfunction patchCreateAstroCompat(component: unknown): AstroComponentFactory {\n  if (typeof component !== 'function') {\n    throw new Error('Expected Astro component factory to be a function.');\n  }\n\n  const originalComponent = component as AstroComponentFactory;\n  const wrapped = ((result: AstroCreateResult, props: unknown, slots: unknown) => {\n    if (result && typeof result.createAstro === 'function') {\n      const originalCreateAstro = result.createAstro;\n      const runtimeExpectsAstroGlobal = originalCreateAstro.length >= 3;\n\n      result.createAstro = (...args: unknown[]) => {\n        if (args.length === 3 && !runtimeExpectsAstroGlobal) {\n          return originalCreateAstro(args[1], args[2]);\n        }\n\n        return originalCreateAstro(...args);\n      };\n    }\n\n    return originalComponent(result, props, slots);\n  }) as AstroComponentFactory;\n\n  wrapped.isAstroComponentFactory = originalComponent.isAstroComponentFactory;\n  wrapped.moduleId = originalComponent.moduleId;\n  wrapped.propagation = originalComponent.propagation;\n\n  return wrapped;\n}\n\nasync function processImageMetadata(\n  args: Record<string, unknown>\n): Promise<Record<string, unknown>> {\n  const processed: Record<string, unknown> = {};\n\n  for (const [key, value] of Object.entries(args)) {\n    if (isImageMetadata(value)) {\n      // Keep ImageMetadata as a plain object — Astro's image service checks\n      // isESMImportedImage (typeof src === 'object') and skips the /@fs/ string\n      // validation that throws LocalImageUsedWrongly. Converting to a URL string\n      // causes that error when the string starts with /@fs/.\n      processed[key] = value;\n\n      continue;\n    }\n\n    if (Array.isArray(value)) {\n      processed[key] = await Promise.all(\n        value.map(async (item) => {\n          if (isImageMetadata(item)) {\n            return item;\n          }\n\n          if (isRecord(item)) {\n            return processImageMetadata(item);\n          }\n\n          return item;\n        })\n      );\n\n      continue;\n    }\n\n    if (isRecord(value)) {\n      processed[key] = await processImageMetadata(value);\n\n      continue;\n    }\n\n    processed[key] = value;\n  }\n\n  return processed;\n}\n\nfunction isImageMetadata(value: unknown): value is Record<string, unknown> {\n  return (\n    isRecord(value) &&\n    typeof value.src === 'string' &&\n    ('width' in value || 'height' in value || 'format' in value)\n  );\n}\n\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null;\n}\n"],"mappings":"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","names":["options"]}
+{"version":3,"sources":["../src/middleware.ts"],"sourcesContent":["import { pathToFileURL } from 'node:url';\nimport { experimental_AstroContainer as AstroContainer } from 'astro/container';\nimport type { Integration } from './integrations/index.ts';\nimport { installPassthroughImageService } from './lib/passthrough-image-service.ts';\nimport type { SanitizationOptions } from './lib/sanitization.ts';\nimport { resolveSanitizationOptions, sanitizeRenderPayload } from './lib/sanitization.ts';\nimport { resolveStoryModuleMock, withStoryModuleMocks } from './module-mocks.ts';\nimport { selectStoryRules, withStoryRuleCleanups } from './rules.ts';\nimport type { RenderStoryInput } from './types.ts';\nimport { addRenderers, resolveClientModules } from 'virtual:astro-container-renderers';\n\ntype ResolveRulesConfigModule = () => unknown | Promise<unknown>;\n\ntype AstroCreateResult = {\n  createAstro?: (...args: unknown[]) => unknown;\n};\n\ntype AstroComponentFactory = ((\n  result: AstroCreateResult,\n  props: unknown,\n  slots: unknown\n) => unknown) & {\n  isAstroComponentFactory?: boolean;\n  moduleId?: string;\n  propagation?: unknown;\n};\n\nexport type HandlerProps = {\n  component: string;\n  args?: Record<string, unknown>;\n  slots?: Record<string, unknown>;\n  story?: RenderStoryInput;\n};\n\ntype HandlerFactoryOptions = {\n  sanitization?: SanitizationOptions;\n  rulesConfigFilePath?: string;\n  resolveRulesConfigModule?: ResolveRulesConfigModule;\n  loadModule?: (id: string) => Promise<{ default: unknown }>;\n};\n\nexport async function handlerFactory(_integrations: Integration[], options?: HandlerFactoryOptions) {\n  // Inject a passthrough image service before any component renders. See\n  // `lib/passthrough-image-service.ts` for why this is necessary.\n  installPassthroughImageService();\n\n  const container = await AstroContainer.create({\n    // Somewhat hacky way to force client-side Storybook's Vite to resolve modules properly\n    resolve: async (specifier) => {\n      const mockedModule = resolveStoryModuleMock(specifier);\n\n      if (mockedModule) {\n        return mockedModule;\n      }\n\n      if (specifier.startsWith('astro:scripts')) {\n        return `/@id/${specifier}`;\n      }\n\n      const resolution = resolveClientModules(specifier);\n\n      if (resolution) {\n        return resolution;\n      }\n\n      return specifier;\n    }\n  });\n\n  addRenderers(container);\n  const sanitizationOptions = resolveSanitizationOptions(options?.sanitization);\n  const loadModule =\n    options?.loadModule ??\n    ((id: string) => {\n      const normalizedId = /^[a-zA-Z]:[/\\\\]/.test(id) ? pathToFileURL(id).href : id;\n\n      return import(/* @vite-ignore */ normalizedId);\n    });\n  const componentCache = new Map<string, Promise<AstroComponentFactory>>();\n  let renderQueue = Promise.resolve<void>(undefined);\n\n  async function loadPatchedComponent(componentId: string, useCache = true) {\n    if (!useCache) {\n      const { default: component } = await loadModule(componentId);\n\n      return patchCreateAstroCompat(component);\n    }\n\n    if (!componentCache.has(componentId)) {\n      componentCache.set(componentId, (async () => {\n        const { default: component } = await loadModule(componentId);\n\n        return patchCreateAstroCompat(component);\n      })());\n    }\n\n    const cachedComponent = componentCache.get(componentId);\n\n    if (!cachedComponent) {\n      throw new Error(`Failed to load Astro component: ${componentId}`);\n    }\n\n    try {\n      return await cachedComponent;\n    } catch (error) {\n      // Drop failed entries so transient/module errors can recover on the next request.\n      componentCache.delete(componentId);\n      throw error;\n    }\n  }\n\n  return async function handler(data: HandlerProps) {\n    const executeRender = async () => {\n      const rulesConfigModule = options?.resolveRulesConfigModule\n        ? await options.resolveRulesConfigModule()\n        : undefined;\n\n      const selectedRules = await selectStoryRules({\n        configModule: rulesConfigModule,\n        configFilePath: options?.rulesConfigFilePath,\n        story: data.story\n      });\n\n      return withStoryRuleCleanups(selectedRules.cleanups, async () => {\n        return withStoryModuleMocks(selectedRules.moduleMocks, async () => {\n          const patchedComponent = await loadPatchedComponent(\n            data.component,\n            selectedRules.moduleMocks.size === 0\n          );\n          const processedArgs = await processImageMetadata(data.args ?? {});\n          const sanitizedPayload = sanitizeRenderPayload(\n            {\n              args: processedArgs,\n              slots: data.slots ?? {}\n            },\n            sanitizationOptions\n          );\n\n          return container.renderToString(\n            patchedComponent as Parameters<typeof container.renderToString>[0],\n            {\n              props: sanitizedPayload.args,\n              slots: sanitizedPayload.slots\n            }\n          );\n        });\n      });\n    };\n\n    const resultPromise = renderQueue.then(executeRender, executeRender);\n\n    renderQueue = resultPromise.then(\n      () => undefined,\n      () => undefined\n    );\n\n    return resultPromise;\n  };\n}\n\nfunction patchCreateAstroCompat(component: unknown): AstroComponentFactory {\n  if (typeof component !== 'function') {\n    throw new Error('Expected Astro component factory to be a function.');\n  }\n\n  const originalComponent = component as AstroComponentFactory;\n  const wrapped = ((result: AstroCreateResult, props: unknown, slots: unknown) => {\n    if (result && typeof result.createAstro === 'function') {\n      const originalCreateAstro = result.createAstro;\n      const runtimeExpectsAstroGlobal = originalCreateAstro.length >= 3;\n\n      result.createAstro = (...args: unknown[]) => {\n        if (args.length === 3 && !runtimeExpectsAstroGlobal) {\n          return originalCreateAstro(args[1], args[2]);\n        }\n\n        return originalCreateAstro(...args);\n      };\n    }\n\n    return originalComponent(result, props, slots);\n  }) as AstroComponentFactory;\n\n  wrapped.isAstroComponentFactory = originalComponent.isAstroComponentFactory;\n  wrapped.moduleId = originalComponent.moduleId;\n  wrapped.propagation = originalComponent.propagation;\n\n  return wrapped;\n}\n\nasync function processImageMetadata(\n  args: Record<string, unknown>\n): Promise<Record<string, unknown>> {\n  const processed: Record<string, unknown> = {};\n\n  for (const [key, value] of Object.entries(args)) {\n    if (isImageMetadata(value)) {\n      // Keep ImageMetadata as a plain object — Astro's image service checks\n      // isESMImportedImage (typeof src === 'object') and skips the /@fs/ string\n      // validation that throws LocalImageUsedWrongly. Converting to a URL string\n      // causes that error when the string starts with /@fs/.\n      processed[key] = value;\n\n      continue;\n    }\n\n    if (Array.isArray(value)) {\n      processed[key] = await Promise.all(\n        value.map(async (item) => {\n          if (isImageMetadata(item)) {\n            return item;\n          }\n\n          if (isRecord(item)) {\n            return processImageMetadata(item);\n          }\n\n          return item;\n        })\n      );\n\n      continue;\n    }\n\n    if (isRecord(value)) {\n      processed[key] = await processImageMetadata(value);\n\n      continue;\n    }\n\n    processed[key] = value;\n  }\n\n  return processed;\n}\n\nfunction isImageMetadata(value: unknown): value is Record<string, unknown> {\n  return (\n    isRecord(value) &&\n    typeof value.src === 'string' &&\n    ('width' in value || 'height' in value || 'format' in value)\n  );\n}\n\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null;\n}\n"],"mappings":"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","names":[]}

package/dist/node/index.d.ts

@@ -1,4 +1,4 @@
-import { d as StorybookConfig } from '../types-Cvor6Tyi.js';
+import { d as StorybookConfig } from '../types-C-jan6Px.js';
 import 'storybook/internal/types';
 import 'vite';
 import '../base-IRZo3zgK.js';

package/dist/{portable-stories-BvdaQigq.d.ts → portable-stories-DXT_GOf6.d.ts}

@@ -24,7 +24,7 @@ interface AstroRenderer extends WebRenderer {
  *
  * @param projectAnnotations - E.g. (import projectAnnotations from '../.storybook/preview')
  */
-declare function setProjectAnnotations(projectAnnotations: NamedOrDefaultProjectAnnotations<AstroRenderer> | NamedOrDefaultProjectAnnotations<AstroRenderer>[]): NormalizedProjectAnnotations<AstroRenderer>;
+declare function setProjectAnnotations<R extends AstroRenderer = AstroRenderer>(projectAnnotations: NamedOrDefaultProjectAnnotations<R> | NamedOrDefaultProjectAnnotations<R>[]): NormalizedProjectAnnotations<R>;
 /**
  * Function that will receive a story along with meta (e.g. a default export from a .stories file)
  * and optionally projectAnnotations e.g. (import * as projectAnnotations from '../.storybook/preview')
@@ -51,7 +51,7 @@ declare function setProjectAnnotations(projectAnnotations: NamedOrDefaultProject
  * @param projectAnnotations - E.g. (import * as projectAnnotations from '../.storybook/preview') this can be applied automatically if you use `setProjectAnnotations` in your setup files.
  * @param exportsName - In case your story does not contain a name and you want it to have a name.
  */
-declare function composeStory<TArgs extends Args = Args>(story: StoryAnnotationsOrFn<AstroRenderer, TArgs>, componentAnnotations: ComponentAnnotations<AstroRenderer, TArgs>, projectAnnotations?: ProjectAnnotations<AstroRenderer>, exportsName?: string): storybook_internal_types.ComposedStoryFn<AstroRenderer, Partial<TArgs>>;
+declare function composeStory<TArgs extends Args = Args, R extends AstroRenderer = AstroRenderer>(story: StoryAnnotationsOrFn<R, TArgs>, componentAnnotations: ComponentAnnotations<R, TArgs>, projectAnnotations?: ProjectAnnotations<R>, exportsName?: string): storybook_internal_types.ComposedStoryFn<AstroRenderer, Partial<TArgs>>;
 /**
  * Function that will receive a stories import (e.g. `import * as stories from './Button.stories'`)
  * and optionally a globalConfig (e.g. `import * from '../.storybook/preview`)
@@ -76,7 +76,7 @@ declare function composeStory<TArgs extends Args = Args>(story: StoryAnnotations
  * @param storiesImport - E.g. (import * as stories from './Button.stories')
  * @param projectAnnotations - E.g. (import * as globalConfig from '../.storybook/preview') this can be applied automatically if you use `setProjectAnnotations` in your setup files.
  */
-declare function composeStories<TModule extends Record<string, any>>(storiesImport: TModule, projectAnnotations?: ProjectAnnotations<AstroRenderer>): {
+declare function composeStories<TModule extends Record<string, any>, R extends AstroRenderer = AstroRenderer>(storiesImport: TModule, projectAnnotations?: ProjectAnnotations<R>): {
     [K in keyof Omit<TModule, 'default'>]: any;
 };
 

package/dist/preset.d.ts

@@ -1,4 +1,4 @@
-import { e as StorybookConfigVite } from './types-Cvor6Tyi.js';
+import { e as StorybookConfigVite } from './types-C-jan6Px.js';
 import 'storybook/internal/types';
 import 'vite';
 import './base-IRZo3zgK.js';

package/dist/preset.js

@@ -1,8 +1,8 @@
 import {
   core,
   viteFinal
-} from "./chunk-4HECE7IW.js";
-import "./chunk-V76WSNSP.js";
+} from "./chunk-PBISP7PA.js";
+import "./chunk-OUEDTRBO.js";
 import "./chunk-POHTFYST.js";
 import "./chunk-E4LB75JN.js";
 import "./chunk-DNGQBPT7.js";

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { A as AstroRenderer, a as composeStory$1, s as setProjectAnnotations$1 } from './portable-stories-BvdaQigq.js';
+import { A as AstroRenderer, a as composeStory$1, s as setProjectAnnotations$1 } from './portable-stories-DXT_GOf6.js';
 import { Store_CSFExports, ProjectAnnotations } from 'storybook/internal/types';
 
 declare function composeStories<TModule extends Store_CSFExports<AstroRenderer> & Record<string, unknown>>(storiesImport: TModule, projectAnnotations?: ProjectAnnotations<AstroRenderer>): { [K in keyof Omit<TModule, "default">]: any; };

package/dist/testing.js

@@ -2,7 +2,7 @@ import {
   composeStories,
   composeStory,
   setProjectAnnotations
-} from "./chunk-5EF25G5S.js";
+} from "./chunk-KXAAX3GN.js";
 import {
   renderViaTestingRendererDaemon,
   runWithWorkingDirectory

package/dist/{types-Cvor6Tyi.d.ts → types-C-jan6Px.d.ts}

@@ -41,6 +41,15 @@ type StaticFrameworkOptions = BaseFrameworkOptions & {
     renderMode: 'static';
     storyRules?: StoryRulesOptions;
     server?: never;
+    /**
+     * Additional source directories (relative to `resolveFrom`) to scan for
+     * hydratable client components (JSX/TSX/Vue/Svelte). Use this when stories
+     * reference components that live outside the default `src/components` scan
+     * root — for example, workspace packages included in the `stories` globs.
+     *
+     * @example ['../../packages/components/src']
+     */
+    componentRoots?: string[];
 };
 type FrameworkOptions = ServerFrameworkOptions | StaticFrameworkOptions;
 type StorybookConfigFramework = {

package/dist/vitest/index.d.ts

@@ -16,4 +16,22 @@ declare function defineConfig(options: TestingDefineConfig): ({ mode: viteMode,
 declare function vitestPatchForSolidJs(): AstroIntegration;
 declare function cjsInteropPlugin(): Plugin;
 
-export { type TestingDefineConfig, cjsInteropPlugin, defineConfig, vitestPatchForSolidJs };
+/**
+ * Vite plugin that patches Astro 6's client-side .astro file transforms for Storybook.
+ *
+ * In Astro 6, the client-side transform of .astro files produces a stub function that
+ * throws "Astro components cannot be used in the browser" without setting the
+ * `isAstroComponentFactory` marker. Storybook's renderer relies on this marker to detect
+ * Astro components and route them to server-side rendering via the Container API.
+ *
+ * This plugin also preserves the component's scoped CSS by importing the style sub-modules
+ * that the Astro Vite plugin exposes. Without this, the client-side stub would strip all
+ * CSS since Astro 6 no longer includes style imports in client-side .astro transforms.
+ *
+ * During builds, Astro's compile metadata cache is not populated for client-side transforms,
+ * so style sub-module imports would fail. Instead, raw CSS is extracted directly from the
+ * .astro source and inlined.
+ */
+declare function vitePluginAstroComponentMarker(): PluginOption;
+
+export { type TestingDefineConfig, cjsInteropPlugin, defineConfig, vitePluginAstroComponentMarker, vitestPatchForSolidJs };

package/dist/vitest/index.js

@@ -241,6 +241,7 @@ function defineConfig2(options) {
 export {
   cjsInteropPlugin,
   defineConfig2 as defineConfig,
+  vitePluginAstroComponentMarker,
   vitestPatchForSolidJs
 };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storybook-astro/framework",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Community-supported Storybook framework for Astro 5 & 6 components",
   "type": "module",
   "license": "MIT",
@@ -115,8 +115,8 @@
     "@storybook/svelte": "^10.0.0",
     "@storybook/vue3": "^10.0.0",
     "@vitejs/plugin-react": "^5.0.0",
-    "@vitejs/plugin-vue": "^5.2.3",
-    "@vitejs/plugin-vue-jsx": "^4.1.2",
+    "@vitejs/plugin-vue": "^5.2.3 || ^6.0.0",
+    "@vitejs/plugin-vue-jsx": "^4.1.2 || ^5.0.0",
     "astro": "^5.5.3 || ^6.0.0",
     "storybook": "^10.0.0",
     "storybook-solidjs": "^1.0.0-beta.7",
@@ -167,7 +167,7 @@
     }
   },
   "dependencies": {
-    "@storybook-astro/renderer": "1.1.1",
+    "@storybook-astro/renderer": "1.2.0",
     "hono": "^4.11.12",
     "sanitize-html": "^2.17.0",
     "vite": "^6.4.1 || ^7.0.0 || ^8.0.0"

package/src/index.ts

@@ -11,8 +11,18 @@ import { definePreview as definePreviewBase, type PreviewAddon, type InferTypes,
 import type { ProjectAnnotations } from 'storybook/internal/types';
 import type { AstroRenderer } from './portable-stories.ts';
 
-/** Preview configuration type for `.storybook/preview.ts` in Astro projects. */
-export type Preview = ProjectAnnotations<AstroRenderer>;
+/**
+ * Preview configuration type for `.storybook/preview.ts` in Astro projects.
+ * Reflects the full type returned by `definePreview`, including addon type extensions.
+ * Use this to annotate your preview module when needed:
+ *
+ * ```ts
+ * import type { Preview } from '@storybook-astro/framework';
+ * const preview: Preview = { ... };
+ * export default preview;
+ * ```
+ */
+export type Preview<Addons extends PreviewAddon<never>[] = []> = CsfPreview<AstroRenderer & InferTypes<Addons>>;
 
 // Export portable stories functionality
 export {

package/src/lib/passthrough-image-service.ts

@@ -0,0 +1,76 @@
+/**
+ * Install a passthrough image service on `globalThis.astroAsset.imageService`.
+ *
+ * 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 — `getConfiguredImageService()` checks this global first and returns
+ * it without going through the broken virtual module. Our service returns the
+ * direct /@fs/... Vite URL from the ImageMetadata object, which Vite can serve
+ * as a static asset in the browser; in static (build-time prerender) mode the
+ * URL ends up being rewritten to a content-hashed Rollup asset.
+ *
+ * This must be called on the same Node process that hosts AstroContainer,
+ * before `container.renderToString()` is invoked.
+ */
+export function installPassthroughImageService() {
+  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: _format,
+        quality: _quality,
+        densities: _densities,
+        widths: _widths,
+        formats: _formats,
+        layout: _layout,
+        priority: _priority,
+        fit: _fit,
+        position: _position,
+        background: _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 [];
+    }
+  };
+}

package/src/middleware.ts

@@ -1,6 +1,7 @@
 import { pathToFileURL } from 'node:url';
 import { experimental_AstroContainer as AstroContainer } from 'astro/container';
 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';
@@ -39,51 +40,9 @@ type HandlerFactoryOptions = {
 };
 
 export async function handlerFactory(_integrations: Integration[], options?: HandlerFactoryOptions) {
-  // 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 [];
-    }
-  };
+  // Inject a passthrough image service before any component renders. See
+  // `lib/passthrough-image-service.ts` for why this is necessary.
+  installPassthroughImageService();
 
   const container = await AstroContainer.create({
     // Somewhat hacky way to force client-side Storybook's Vite to resolve modules properly

package/src/portable-stories.test.ts

@@ -0,0 +1,28 @@
+/**
+ * Type-level tests for portable-stories utilities.
+ *
+ * These tests verify that setProjectAnnotations, composeStory, and composeStories
+ * accept the widened renderer type produced by definePreview when addons are used.
+ * Without the generic R parameter, users get "has no properties in common" errors
+ * when passing a definePreview result to setProjectAnnotations.
+ *
+ * See: https://github.com/storybook-astro/storybook-astro/issues/58
+ */
+import { expectTypeOf, test } from 'vitest';
+import type { NormalizedProjectAnnotations } from 'storybook/internal/types';
+import { definePreview, setProjectAnnotations, type AstroRenderer } from './index.ts';
+
+test('setProjectAnnotations accepts a module whose default export is a widened Preview type', () => {
+  // This is the shape of `import * as preview from '.storybook/preview'`
+  // when the preview uses definePreview with addons.
+  type PreviewModule = { default: ReturnType<typeof definePreview<[]>> };
+
+  expectTypeOf<(annotations: PreviewModule) => NormalizedProjectAnnotations<AstroRenderer>>()
+    .toBeCallableWith({ default: definePreview({}) });
+});
+
+test('setProjectAnnotations return type narrows correctly for base AstroRenderer', () => {
+  const result = setProjectAnnotations([]);
+
+  expectTypeOf(result).toMatchTypeOf<NormalizedProjectAnnotations<AstroRenderer>>();
+});

package/src/portable-stories.ts

@@ -89,12 +89,12 @@ const render = (args: Args, context?: any) => {
  *
  * @param projectAnnotations - E.g. (import projectAnnotations from '../.storybook/preview')
  */
-export function setProjectAnnotations(
+export function setProjectAnnotations<R extends AstroRenderer = AstroRenderer>(
   projectAnnotations:
-    | NamedOrDefaultProjectAnnotations<AstroRenderer>
-    | NamedOrDefaultProjectAnnotations<AstroRenderer>[]
-): NormalizedProjectAnnotations<AstroRenderer> {
-  return originalSetProjectAnnotations<AstroRenderer>(projectAnnotations);
+    | NamedOrDefaultProjectAnnotations<R>
+    | NamedOrDefaultProjectAnnotations<R>[]
+): NormalizedProjectAnnotations<R> {
+  return originalSetProjectAnnotations<R>(projectAnnotations);
 }
 
 /**
@@ -123,10 +123,10 @@ export function setProjectAnnotations(
  * @param projectAnnotations - E.g. (import * as projectAnnotations from '../.storybook/preview') this can be applied automatically if you use `setProjectAnnotations` in your setup files.
  * @param exportsName - In case your story does not contain a name and you want it to have a name.
  */
-export function composeStory<TArgs extends Args = Args>(
-  story: StoryAnnotationsOrFn<AstroRenderer, TArgs>,
-  componentAnnotations: ComponentAnnotations<AstroRenderer, TArgs>,
-  projectAnnotations?: ProjectAnnotations<AstroRenderer>,
+export function composeStory<TArgs extends Args = Args, R extends AstroRenderer = AstroRenderer>(
+  story: StoryAnnotationsOrFn<R, TArgs>,
+  componentAnnotations: ComponentAnnotations<R, TArgs>,
+  projectAnnotations?: ProjectAnnotations<R>,
   exportsName?: string
 ) {
   // Merge project annotations with Astro renderer
@@ -139,7 +139,7 @@ export function composeStory<TArgs extends Args = Args>(
   
   return originalComposeStory<AstroRenderer, TArgs>(
     story as any,
-    componentAnnotations,
+    componentAnnotations as any,
     mergedProjectAnnotations as any,
     exportsName as any
   );
@@ -169,9 +169,9 @@ export function composeStory<TArgs extends Args = Args>(
  * @param storiesImport - E.g. (import * as stories from './Button.stories')
  * @param projectAnnotations - E.g. (import * as globalConfig from '../.storybook/preview') this can be applied automatically if you use `setProjectAnnotations` in your setup files.
  */
-export function composeStories<TModule extends Record<string, any>>(
+export function composeStories<TModule extends Record<string, any>, R extends AstroRenderer = AstroRenderer>(
   storiesImport: TModule,
-  projectAnnotations?: ProjectAnnotations<AstroRenderer>
+  projectAnnotations?: ProjectAnnotations<R>
 ): { [K in keyof Omit<TModule, 'default'>]: any } {
   // Merge project annotations with Astro renderer
   const mergedProjectAnnotations: any = projectAnnotations ? {

package/src/types.ts

@@ -37,6 +37,15 @@ type StaticFrameworkOptions = BaseFrameworkOptions & {
   renderMode: 'static';
   storyRules?: StoryRulesOptions;
   server?: never;
+  /**
+   * Additional source directories (relative to `resolveFrom`) to scan for
+   * hydratable client components (JSX/TSX/Vue/Svelte). Use this when stories
+   * reference components that live outside the default `src/components` scan
+   * root — for example, workspace packages included in the `stories` globs.
+   *
+   * @example ['../../packages/components/src']
+   */
+  componentRoots?: string[];
 };
 
 export type FrameworkOptions = ServerFrameworkOptions | StaticFrameworkOptions;