sdocs 0.0.25 → 0.0.28

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.28] - 2026-07-03
+
+### Changed
+
+- **`sdocs dev`/`run`/`build` no longer write a `.sdocs/` directory into the
+  project.** The generated app is staged in a unique directory under
+  `node_modules/.cache/` (imports resolve exactly as before) and removed on
+  exit. This also fixes `sdocs build` breaking a concurrently running dev
+  server — they previously shared the same staging directory.
+
+## [0.0.27] - 2026-07-03
+
+### Added
+
+- **`sdocs run`** — same as `dev`, built for `npx sdocs run`: works with no
+  local install. The dev server allows sdocs' own files from the npx cache,
+  and when the project has its own `svelte`, previews dedupe onto it, so
+  components and their dependencies always resolve from the project.
+
+### Changed
+
+- `sdocs build` applies the same svelte dedupe as the dev server.
+
+## [0.0.26] - 2026-07-03
+
+### Fixed
+
+- **Embedded production builds now include working previews.** The Vite
+  plugin emits each preview as a static page (plus your `css` stylesheets)
+  into the host app's client build under `previews/`, and `virtual:sdocs`
+  references those pages — preview iframes no longer 404 in deployed apps.
+- The standalone CLI (`sdocs dev`/`sdocs build`) failed from an installed
+  package: the client app was staged from a wrong path, and its `ui/` styles
+  and fonts were not staged at all.
+- The docs UI stops calling the dev-only highlight endpoint after the first
+  failure in production and falls back to plain code.
+
 ## [0.0.25] - 2026-07-02
 
 ### Added

package/dist/client/views/ComponentView.svelte

@@ -169,13 +169,20 @@
 		return generateFallbackCode(componentName, propValues, cssValues);
 	});
 
-	// Highlighted usage code via server-side Shiki
+	// Highlighted usage code via server-side Shiki. The endpoint is dev-server
+	// middleware; in a production build it doesn't exist, so after the first
+	// failure stop asking and fall back to plain code.
 	let highlightedUsageHtml = $state('');
 	let highlightTimer: ReturnType<typeof setTimeout> | undefined;
+	let highlightAvailable = true;
 
 	$effect(() => {
 		const code = usageCode;
 		clearTimeout(highlightTimer);
+		if (!highlightAvailable) {
+			highlightedUsageHtml = '';
+			return;
+		}
 		highlightTimer = setTimeout(async () => {
 			try {
 				const res = await fetch('/__sdocs/highlight', {
@@ -186,9 +193,13 @@
 				if (res.ok) {
 					const { html } = await res.json();
 					highlightedUsageHtml = html;
+				} else {
+					highlightAvailable = false;
+					highlightedUsageHtml = '';
 				}
 			} catch {
-				// Fallback: leave previous value
+				highlightAvailable = false;
+				highlightedUsageHtml = '';
 			}
 		}, 150);
 	});

package/dist/commands/build.js

@@ -4,11 +4,12 @@ import { svelte } from '@sveltejs/vite-plugin-svelte';
 import { loadConfig } from '../server/config.js';
 import { sdocsPlugin } from '../vite.js';
 import { generateBuildFiles, cleanBuildFiles } from '../server/app-gen.js';
+import { svelteDedupe } from './dev.js';
 export async function buildCommand() {
     const cwd = process.cwd();
     const config = await loadConfig(cwd);
     console.log('[sdocs] Building static site...');
-    // Generate .sdocs/ with entry + preview HTML files
+    // Generate the staging directory (in the OS temp dir) with entry + preview HTML files
     const { sdocsDir, inputs } = await generateBuildFiles(config, cwd);
     const inputCount = Object.keys(inputs).length;
     console.log(`[sdocs] Generated ${inputCount} page(s) (1 main + ${inputCount - 1} previews)`);
@@ -18,6 +19,9 @@ export async function buildCommand() {
         await build({
             configFile: false,
             root: sdocsDir,
+            resolve: {
+                dedupe: svelteDedupe(cwd),
+            },
             plugins: [
                 svelte(),
                 sdocsPlugin({ ...config, include: absoluteIncludes, _buildMode: true }),
@@ -33,6 +37,6 @@ export async function buildCommand() {
         console.log(`[sdocs] Build complete → dist/`);
     }
     finally {
-        await cleanBuildFiles(cwd);
+        await cleanBuildFiles(sdocsDir);
     }
 }

package/dist/commands/dev.d.ts

@@ -1 +1,9 @@
+/** sdocs' own install location — under npx this is the npx cache, not the project */
+export declare function sdocsPackageRoot(): string;
+/**
+ * Prefer the project's own svelte over the copy next to sdocs when both exist
+ * (e.g. running via npx): previews import the project's components, and two
+ * svelte runtimes in one page don't mix.
+ */
+export declare function svelteDedupe(cwd: string): string[];
 export declare function devCommand(): Promise<void>;

package/dist/commands/dev.js

@@ -1,20 +1,45 @@
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 import { createServer } from 'vite';
 import { svelte } from '@sveltejs/vite-plugin-svelte';
 import { loadConfig } from '../server/config.js';
 import { sdocsPlugin } from '../vite.js';
 import { generateDevFiles, cleanBuildFiles } from '../server/app-gen.js';
+const require = createRequire(import.meta.url);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** sdocs' own install location — under npx this is the npx cache, not the project */
+export function sdocsPackageRoot() {
+    return resolve(__dirname, '../..');
+}
+/**
+ * Prefer the project's own svelte over the copy next to sdocs when both exist
+ * (e.g. running via npx): previews import the project's components, and two
+ * svelte runtimes in one page don't mix.
+ */
+export function svelteDedupe(cwd) {
+    try {
+        require.resolve('svelte/package.json', { paths: [cwd] });
+        return ['svelte'];
+    }
+    catch {
+        return [];
+    }
+}
 export async function devCommand() {
     const cwd = process.cwd();
     const config = await loadConfig(cwd);
     console.log('[sdocs] Starting dev server...');
-    // Generate .sdocs/ temp directory with entry files
+    // Generate the staging directory (in the OS temp dir) with entry files
     const sdocsDir = await generateDevFiles(config, cwd);
-    // Resolve include patterns to absolute paths (relative to cwd, not .sdocs/)
+    // Resolve include patterns to absolute paths (relative to cwd, not the staging dir)
     const absoluteIncludes = config.include.map((p) => resolve(cwd, p));
     const server = await createServer({
         configFile: false,
         root: sdocsDir,
+        resolve: {
+            dedupe: svelteDedupe(cwd),
+        },
         plugins: [
             svelte(),
             sdocsPlugin({ ...config, include: absoluteIncludes }),
@@ -23,7 +48,10 @@ export async function devCommand() {
             port: config.port,
             open: config.open,
             fs: {
-                allow: [cwd],
+                // The staging dir (an explicit allow list replaces Vite's implicit
+                // root allowance), the project, and sdocs' own dependency tree
+                // (the npx cache when running without a local install).
+                allow: [sdocsDir, cwd, resolve(sdocsPackageRoot(), '..')],
             },
         },
     });
@@ -32,7 +60,7 @@ export async function devCommand() {
     // Cleanup on exit
     const cleanup = async () => {
         await server.close();
-        await cleanBuildFiles(cwd);
+        await cleanBuildFiles(sdocsDir);
         process.exit(0);
     };
     process.on('SIGINT', cleanup);

package/dist/server/app-gen.d.ts

@@ -1,10 +1,10 @@
 import type { ResolvedSdocsConfig } from '../types.js';
-/** Generate .sdocs/ directory with entry files for dev mode */
+/** Generate the staging directory with entry files for dev mode */
 export declare function generateDevFiles(config: ResolvedSdocsConfig, cwd: string): Promise<string>;
-/** Generate .sdocs/ directory with entry + preview HTML files for build mode */
+/** Generate the staging directory with entry + preview HTML files for build mode */
 export declare function generateBuildFiles(config: ResolvedSdocsConfig, cwd: string): Promise<{
     sdocsDir: string;
     inputs: Record<string, string>;
 }>;
-/** Remove the .sdocs/ temp directory */
-export declare function cleanBuildFiles(cwd: string): Promise<void>;
+/** Remove a staging directory created by generateDevFiles/generateBuildFiles */
+export declare function cleanBuildFiles(stagingDir: string): Promise<void>;

package/dist/server/app-gen.js

@@ -1,13 +1,50 @@
-import { mkdir, writeFile, rm, readFile, copyFile, readdir } from 'node:fs/promises';
+import { mkdir, mkdtemp, writeFile, rm, readFile, copyFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { dirname, resolve, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { discoverDocFiles, getSdocKind } from './discovery.js';
 import { extractSnippets, hasDefaultSnippet } from './snippet-extractor.js';
 import { base64urlEncode } from './snippet-compiler.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
-/** Source client directory in the installed package */
+/** Source client directory in the installed package (dist/client, next to dist/server) */
 function getClientSourceDir() {
-    return resolve(__dirname, 'client');
+    return resolve(__dirname, '../client');
+}
+/** Copy the client app plus the ui/ tree it imports (styles, fonts, components) */
+async function copyClientApp(sdocsDir) {
+    await copyDir(getClientSourceDir(), resolve(sdocsDir, 'client'));
+    await copyDir(resolve(__dirname, '../ui'), resolve(sdocsDir, 'ui'));
+}
+/** Nearest node_modules walking up from dir (mirrors Node's resolution) */
+function findNearestNodeModules(dir) {
+    let current = resolve(dir);
+    for (;;) {
+        const candidate = join(current, 'node_modules');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/**
+ * Create a unique staging directory for the generated app. It lives inside
+ * node_modules/.cache — never a tracked file in the user's project — and being
+ * physically inside node_modules keeps the full walk-up resolution chain for
+ * bare imports (svelte, ...) intact, including hoisted monorepo setups. When
+ * no node_modules exists anywhere (running via npx in a bare folder), sdocs'
+ * own tree provides one; the OS temp dir is the last resort.
+ */
+async function createStagingDir(cwd) {
+    const nodeModules = findNearestNodeModules(cwd) ?? findNearestNodeModules(resolve(__dirname, '..'));
+    if (nodeModules) {
+        const cacheDir = join(nodeModules, '.cache');
+        await mkdir(cacheDir, { recursive: true });
+        return mkdtemp(join(cacheDir, 'sdocs-'));
+    }
+    return mkdtemp(join(tmpdir(), 'sdocs-'));
 }
 /** Copy a directory recursively */
 async function copyDir(src, dest) {
@@ -124,22 +161,20 @@ async function discoverSnippets(config, cwd) {
     }
     return results;
 }
-/** Generate .sdocs/ directory with entry files for dev mode */
+/** Generate the staging directory with entry files for dev mode */
 export async function generateDevFiles(config, cwd) {
-    const sdocsDir = resolve(cwd, '.sdocs');
-    await mkdir(sdocsDir, { recursive: true });
-    // Copy client components into .sdocs/client/ so they're compiled outside node_modules
-    await copyDir(getClientSourceDir(), resolve(sdocsDir, 'client'));
+    const sdocsDir = await createStagingDir(cwd);
+    // Copy client components into the staging dir so they're compiled outside node_modules
+    await copyClientApp(sdocsDir);
     await writeFile(resolve(sdocsDir, 'index.html'), generateIndexHtml(config.logo));
     await writeFile(resolve(sdocsDir, 'entry.js'), generateEntryJs(config));
     return sdocsDir;
 }
-/** Generate .sdocs/ directory with entry + preview HTML files for build mode */
+/** Generate the staging directory with entry + preview HTML files for build mode */
 export async function generateBuildFiles(config, cwd) {
-    const sdocsDir = resolve(cwd, '.sdocs');
-    await mkdir(sdocsDir, { recursive: true });
-    // Copy client components into .sdocs/client/
-    await copyDir(getClientSourceDir(), resolve(sdocsDir, 'client'));
+    const sdocsDir = await createStagingDir(cwd);
+    // Copy client components into the staging dir
+    await copyClientApp(sdocsDir);
     await writeFile(resolve(sdocsDir, 'index.html'), generateIndexHtml(config.logo));
     await writeFile(resolve(sdocsDir, 'entry.js'), generateEntryJs(config));
     const inputs = {
@@ -161,8 +196,7 @@ export async function generateBuildFiles(config, cwd) {
     }
     return { sdocsDir, inputs };
 }
-/** Remove the .sdocs/ temp directory */
-export async function cleanBuildFiles(cwd) {
-    const sdocsDir = resolve(cwd, '.sdocs');
-    await rm(sdocsDir, { recursive: true, force: true });
+/** Remove a staging directory created by generateDevFiles/generateBuildFiles */
+export async function cleanBuildFiles(stagingDir) {
+    await rm(stagingDir, { recursive: true, force: true });
 }

package/dist/server/cli.js

@@ -18,7 +18,8 @@ Usage:
   sdocs <command>
 
 Commands:
-  dev       Start development server with HMR
+  dev       Start development server with live reload
+  run       Same as dev — works with npx and no local install
   build     Build static documentation site
   preview   Serve built site locally
   init      Scaffold sdocs.config.js
@@ -39,7 +40,8 @@ async function main() {
         return;
     }
     switch (command) {
-        case 'dev': {
+        case 'dev':
+        case 'run': {
             const { devCommand } = await import('../commands/dev.js');
             await devCommand();
             break;

package/dist/server/snippet-compiler.d.ts

@@ -7,14 +7,30 @@ export declare function resolveImportsToAbsolute(imports: string[], docFilePath:
 /** Generate a virtual Svelte iframe wrapper component for a snippet.
  * Includes $state for reactive prop updates via postMessage. */
 export declare function generateIframeComponent(absoluteImports: string[], snippetBody: string): string;
-/** Generate the HTML page served inside the iframe */
+/** The JS that boots a preview page: mount the wrapper + parent-frame messaging. */
+export declare function generateMountScript(iframeComponentId: string): string;
+/** Generate the HTML page served inside the iframe (dev / CLI-build inputs) */
 export declare function generatePreviewHtml(iframeComponentId: string, css: string | Record<string, string> | null): string;
+export interface StaticCssLink {
+    href: string;
+    name?: string;
+    disabled?: boolean;
+}
+/** Generate the HTML page for a preview emitted into a host app's build. */
+export declare function generateStaticPreviewHtml(scriptSrc: string, cssLinks: StaticCssLink[]): string;
 /** Build the virtual module ID for an iframe wrapper component */
 export declare function iframeVirtualId(docFilePath: string, snippetName: string): string;
 /** Build the preview URL for an iframe HTML page (dev mode) */
 export declare function previewUrl(docFilePath: string, snippetName: string): string;
 /** Build the preview URL for static build output */
 export declare function buildPreviewUrl(docFilePath: string, snippetName: string): string;
+/** Virtual module ID for a preview's mount script (embedded production builds) */
+export declare function mountVirtualId(docFilePath: string, snippetName: string): string;
+/** Parse a mount virtual ID back into its parts */
+export declare function parseMountId(id: string): {
+    docFilePath: string;
+    snippetName: string;
+} | null;
 /** Parse an iframe virtual ID back into its parts */
 export declare function parseIframeId(id: string): {
     docFilePath: string;

package/dist/server/snippet-compiler.js

@@ -97,9 +97,27 @@ function generateCssLinks(css) {
         .map((name, i) => `<link rel="stylesheet" href="${normalizeCssHref(css[name])}" data-sdocs-stylesheet="${name}"${i > 0 ? ' disabled' : ''}>`)
         .join('\n\t');
 }
-/** Generate the HTML page served inside the iframe */
-export function generatePreviewHtml(iframeComponentId, css) {
-    const cssLinks = generateCssLinks(css);
+/** The JS that boots a preview page: mount the wrapper + parent-frame messaging. */
+export function generateMountScript(iframeComponentId) {
+    return `import { mount } from 'svelte';
+import App from '${iframeComponentId}';
+mount(App, { target: document.getElementById('app') });
+
+// Listen for sdocs messages from the parent frame
+window.addEventListener('message', (e) => {
+	if (e.data?.type === 'sdocs:update-stylesheet') {
+		const name = e.data.name;
+		document.querySelectorAll('link[data-sdocs-stylesheet]').forEach((link) => {
+			link.disabled = link.dataset.sdocsStylesheet !== name;
+		});
+	}
+	if (e.data?.type === 'sdocs:scroll-to') {
+		const el = document.getElementById(e.data.id);
+		if (el) el.scrollIntoView({ behavior: 'smooth' });
+	}
+});`;
+}
+function previewHtmlShell(cssLinks, script) {
     return `<!DOCTYPE html>
 <html>
 <head>
@@ -110,28 +128,26 @@ export function generatePreviewHtml(iframeComponentId, css) {
 </head>
 <body>
 	<div id="app"></div>
-	<script type="module">
-		import { mount } from 'svelte';
-		import App from '${iframeComponentId}';
-		mount(App, { target: document.getElementById('app') });
-
-		// Listen for sdocs messages from the parent frame
-		window.addEventListener('message', (e) => {
-			if (e.data?.type === 'sdocs:update-stylesheet') {
-				const name = e.data.name;
-				document.querySelectorAll('link[data-sdocs-stylesheet]').forEach((link) => {
-					link.disabled = link.dataset.sdocsStylesheet !== name;
-				});
-			}
-			if (e.data?.type === 'sdocs:scroll-to') {
-				const el = document.getElementById(e.data.id);
-				if (el) el.scrollIntoView({ behavior: 'smooth' });
-			}
-		});
-	</script>
+	${script}
 </body>
 </html>`;
 }
+/** Generate the HTML page served inside the iframe (dev / CLI-build inputs) */
+export function generatePreviewHtml(iframeComponentId, css) {
+    return previewHtmlShell(generateCssLinks(css), `<script type="module">
+${generateMountScript(iframeComponentId)}
+	</script>`);
+}
+/** Generate the HTML page for a preview emitted into a host app's build. */
+export function generateStaticPreviewHtml(scriptSrc, cssLinks) {
+    const links = cssLinks
+        .map(({ href, name, disabled }) => {
+        const named = name ? ` data-sdocs-stylesheet="${name}"` : '';
+        return `<link rel="stylesheet" href="${href}"${named}${disabled ? ' disabled' : ''}>`;
+    })
+        .join('\n\t');
+    return previewHtmlShell(links, `<script type="module" src="${scriptSrc}"></script>`);
+}
 /** Build the virtual module ID for an iframe wrapper component */
 export function iframeVirtualId(docFilePath, snippetName) {
     return `/@sdocs/iframe/${base64urlEncode(docFilePath)}/${snippetName}.svelte`;
@@ -144,6 +160,20 @@ export function previewUrl(docFilePath, snippetName) {
 export function buildPreviewUrl(docFilePath, snippetName) {
     return `/previews/${base64urlEncode(docFilePath)}/${snippetName}.html`;
 }
+/** Virtual module ID for a preview's mount script (embedded production builds) */
+export function mountVirtualId(docFilePath, snippetName) {
+    return `/@sdocs/mount/${base64urlEncode(docFilePath)}/${snippetName}.js`;
+}
+/** Parse a mount virtual ID back into its parts */
+export function parseMountId(id) {
+    const match = id.match(/^\/@sdocs\/mount\/([^/]+)\/(\w+)\.js$/);
+    if (!match)
+        return null;
+    return {
+        docFilePath: base64urlDecode(match[1]),
+        snippetName: match[2],
+    };
+}
 /** Parse an iframe virtual ID back into its parts */
 export function parseIframeId(id) {
     const match = id.match(/^\/@sdocs\/iframe\/([^/]+)\/(\w+)\.svelte$/);

package/dist/vite.js

@@ -6,11 +6,12 @@ import { parseComponent } from './server/prop-parser.js';
 import { extractSnippets, extractMarkupBody, hasDefaultSnippet, generateAutoDefault, } from './server/snippet-extractor.js';
 import { highlight, disposeHighlighter } from './server/highlighter.js';
 import { extractTocFromHtml } from './server/toc-extractor.js';
-import { parseIframeId, parsePreviewUrl, resolveImportsToAbsolute, generateIframeComponent, generatePreviewHtml, iframeVirtualId, previewUrl, buildPreviewUrl, } from './server/snippet-compiler.js';
+import { parseIframeId, parseMountId, parsePreviewUrl, resolveImportsToAbsolute, generateIframeComponent, generateMountScript, generatePreviewHtml, generateStaticPreviewHtml, iframeVirtualId, mountVirtualId, previewUrl, buildPreviewUrl, base64urlEncode, } from './server/snippet-compiler.js';
 const VIRTUAL_MODULE_ID = 'virtual:sdocs';
 const RESOLVED_VIRTUAL_ID = '\0virtual:sdocs';
 const IFRAME_PREFIX = '/@sdocs/iframe/';
 const PREVIEW_PREFIX = '/@sdocs/preview/';
+const MOUNT_PREFIX = '/@sdocs/mount/';
 export function sdocsPlugin(userConfig) {
     let config;
     let root;
@@ -18,10 +19,17 @@ export function sdocsPlugin(userConfig) {
     let docEntries = new Map();
     let docImportsCache = new Map();
     const buildMode = userConfig?._buildMode ?? false;
+    let isBuild = false;
+    let isSsrBuild = false;
+    // Previews planned for emission into a host app's build (embedded mode)
+    let plannedPreviews = [];
+    let emittedCssLinks = [];
     return {
         name: 'sdocs',
         async configResolved(resolvedConfig) {
             root = resolvedConfig.root;
+            isBuild = resolvedConfig.command === 'build';
+            isSsrBuild = !!resolvedConfig.build?.ssr;
             const fileConfig = await loadRawConfig(root);
             const merged = { ...fileConfig, ...userConfig };
             config = resolveAndFinalize(merged, root);
@@ -125,12 +133,85 @@ export function sdocsPlugin(userConfig) {
                     server.watcher.add(dir);
                 }
             }
+            // Embedded production build: emit each preview as its own chunk so the
+            // host app's build output contains working static preview pages. (The
+            // standalone CLI build passes _buildMode and provides HTML inputs itself;
+            // the SSR half of an app build has no use for browser preview pages.)
+            if (isBuild && !buildMode && !isSsrBuild) {
+                plannedPreviews = [];
+                emittedCssLinks = [];
+                const css = config.css;
+                if (typeof css === 'string') {
+                    emittedCssLinks.push({ href: await emitCssAsset(this, css, 'preview') });
+                }
+                else if (css) {
+                    for (const [i, name] of Object.keys(css).entries()) {
+                        emittedCssLinks.push({
+                            href: await emitCssAsset(this, css[name], name),
+                            name,
+                            disabled: i > 0,
+                        });
+                    }
+                }
+                for (const entry of docEntries.values()) {
+                    const encoded = base64urlEncode(entry.filePath);
+                    for (const snippet of entry.snippets) {
+                        const jsFileName = `previews/${encoded}/${snippet.name}.js`;
+                        this.emitFile({
+                            type: 'chunk',
+                            id: mountVirtualId(entry.filePath, snippet.name),
+                            fileName: jsFileName,
+                        });
+                        plannedPreviews.push({
+                            jsFileName,
+                            htmlFileName: `previews/${encoded}/${snippet.name}.html`,
+                        });
+                    }
+                }
+                console.log(`[sdocs] Emitting ${plannedPreviews.length} static preview page(s)`);
+            }
+        },
+        generateBundle(_options, bundle) {
+            for (const preview of plannedPreviews) {
+                const chunk = bundle[preview.jsFileName];
+                if (!chunk || chunk.type !== 'chunk')
+                    continue;
+                // Collect CSS emitted for this chunk and everything it imports.
+                const cssFiles = new Set();
+                const queue = [preview.jsFileName];
+                const seen = new Set();
+                while (queue.length) {
+                    const fileName = queue.pop();
+                    if (seen.has(fileName))
+                        continue;
+                    seen.add(fileName);
+                    const mod = bundle[fileName];
+                    if (!mod || mod.type !== 'chunk')
+                        continue;
+                    for (const css of mod.viteMetadata?.importedCss ?? [])
+                        cssFiles.add(css);
+                    queue.push(...mod.imports);
+                }
+                // The HTML sits at previews/<doc>/<name>.html — two levels deep.
+                const cssLinks = [
+                    ...emittedCssLinks,
+                    ...[...cssFiles].map((file) => ({ href: `../../${file}` })),
+                ];
+                this.emitFile({
+                    type: 'asset',
+                    fileName: preview.htmlFileName,
+                    source: generateStaticPreviewHtml(`./${preview.jsFileName.split('/').pop()}`, cssLinks),
+                });
+            }
+            plannedPreviews = [];
         },
         resolveId(id) {
             if (id === VIRTUAL_MODULE_ID)
                 return RESOLVED_VIRTUAL_ID;
             if (id.startsWith(IFRAME_PREFIX))
                 return '\0' + id;
+            if (id.startsWith(MOUNT_PREFIX))
+                return '\0' + id;
         },
         load(id) {
             if (id === RESOLVED_VIRTUAL_ID) {
@@ -151,6 +232,13 @@ export function sdocsPlugin(userConfig) {
                 const absoluteImports = docImportsCache.get(parsed.docFilePath) ?? [];
                 return generateIframeComponent(absoluteImports, snippet.body);
             }
+            // Virtual mount script for an emitted preview page
+            if (id.startsWith('\0' + MOUNT_PREFIX)) {
+                const parsed = parseMountId(id.slice(1));
+                if (!parsed)
+                    return null;
+                return generateMountScript(iframeVirtualId(parsed.docFilePath, parsed.snippetName));
+            }
         },
         async buildEnd() {
             await disposeHighlighter();
@@ -232,7 +320,9 @@ export function sdocsPlugin(userConfig) {
                 name: s.name,
                 body: s.body,
                 highlightedHtml: s.highlightedHtml,
-                previewUrl: buildMode ? buildPreviewUrl(e.filePath, s.name) : previewUrl(e.filePath, s.name),
+                previewUrl: buildMode || isBuild
+                    ? buildPreviewUrl(e.filePath, s.name)
+                    : previewUrl(e.filePath, s.name),
             })),
             highlightedSource: e.highlightedSource,
             toc: e.toc,
@@ -269,6 +359,15 @@ export function sdocsPlugin(userConfig) {
     function isDocFile(filePath) {
         return filePath.endsWith('.sdoc');
     }
+    /** Emit a user stylesheet as a build asset; returns its href relative to a preview page. */
+    async function emitCssAsset(ctx, href, name) {
+        if (href.startsWith('http'))
+            return href;
+        const source = await readFile(href, 'utf-8');
+        const fileName = `previews/_css/${name}.css`;
+        ctx.emitFile({ type: 'asset', fileName, source });
+        return `../../${fileName}`;
+    }
     function isComponentReferencedByDoc(filePath) {
         for (const entry of docEntries.values()) {
             if (entry.componentPath === filePath)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdocs",
-  "version": "0.0.25",
+  "version": "0.0.28",
   "description": "A lightweight documentation tool for Svelte 5 components",
   "type": "module",
   "license": "MIT",