sdocs 0.0.25 → 0.0.26

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/server/app-gen.js

@@ -5,9 +5,14 @@ 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'));
 }
 /** Copy a directory recursively */
 async function copyDir(src, dest) {
@@ -129,7 +134,7 @@ 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'));
+    await copyClientApp(sdocsDir);
     await writeFile(resolve(sdocsDir, 'index.html'), generateIndexHtml(config.logo));
     await writeFile(resolve(sdocsDir, 'entry.js'), generateEntryJs(config));
     return sdocsDir;
@@ -139,7 +144,7 @@ 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'));
+    await copyClientApp(sdocsDir);
     await writeFile(resolve(sdocsDir, 'index.html'), generateIndexHtml(config.logo));
     await writeFile(resolve(sdocsDir, 'entry.js'), generateEntryJs(config));
     const inputs = {

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.26",
   "description": "A lightweight documentation tool for Svelte 5 components",
   "type": "module",
   "license": "MIT",