sdocs 0.0.23 → 0.0.26

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to the `sdocs` package are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [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
+
+- **JSDoc prop extraction for plain-JS components.** Both `@type {{ ... }}`
+  object annotations and `@typedef {Object} Props` with `@property` tags on
+  the `$props()` declaration are parsed — types, optionality (bracketed
+  names), and descriptions all flow into the docs and interactive controls.
+- A prop-parser test suite; `npm test` now runs it.
+
+### Fixed
+
+- Props typed as `import('svelte').Snippet` are classified as snippets.
+
+## [0.0.24] - 2026-07-02
+
+### Changed
+
+- Snippets receive `args` as a real snippet parameter: write
+  `{#snippet Default(args)}`. Previews render snippets through `{@render}`,
+  so `args` is an explicit, editor-visible binding instead of a value injected
+  into scope. Parameterless snippets keep working unchanged.
+
+## [0.0.23] - 2026-04-16
+
+First documented release. `sdocs` is a lightweight documentation tool for Svelte 5
+components; this entry describes its capabilities as of 0.0.23.
+
+### Added
+
+- **CLI** — `sdocs dev`, `sdocs build`, `sdocs preview`, and `sdocs init`.
+- **Vite plugin** (`sdocs/vite`) for embedding the explorer in an existing Vite or
+  SvelteKit app, exposing discovered docs through the `virtual:sdocs` module.
+- **Three `.sdoc` kinds** — component docs (`.sdoc`), standalone pages
+  (`.page.sdoc`), and full-page layouts (`.layout.sdoc`).
+- **Prop extraction** from component types, rendered as a props table.
+- **Interactive controls** for live-editing component props and CSS custom
+  properties.
+- **Theming** with light and dark modes and named-stylesheet switching.
+- **Configurable sidebar** ordering and hash-based routing.
+- **Syntax highlighting** via Shiki.
+- Package entry points: `sdocs`, `sdocs/vite`, `sdocs/client`, and `sdocs/ui`.
+
+## [0.0.20] - 2026-04-15
+
+### Changed
+
+- Redesigned the component view and added snippet-based preview code.
+
+## [0.0.18] - 2026-02-27
+
+### Changed
+
+- Scoped the explorer's CSS under `.sdocs-app` to keep its styles from leaking
+  into component previews.
+
+## [0.0.17] - 2026-02-27
+
+### Fixed
+
+- Corrected the `Icon` component imports.
+
+## [0.0.16] - 2026-02-27
+
+### Added
+
+- Rewritten codebase: the current architecture for `.sdoc` discovery, preview
+  rendering, and the component explorer UI.

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/config.js

@@ -58,7 +58,7 @@ export function resolveAndFinalize(userConfig, root) {
     resolved.css = resolveCssPaths(resolved.css, root);
     return resolved;
 }
-/** Import a config file (supports .js, .mjs, .ts via Vite) */
+/** Import a config file (.js/.mjs; .ts only on Node with native type stripping) */
 async function importConfig(configPath) {
     // Use dynamic import with file:// URL for ESM compatibility
     const mod = await import(pathToFileURL(configPath).href);

package/dist/server/prop-parser.js

@@ -15,9 +15,16 @@ export function parseComponentSource(source) {
     if (scriptContent) {
         const tsAst = ts.createSourceFile('component.ts', scriptContent, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
         const interfaceProps = parseInterfaceProps(tsAst);
+        const jsdocTypeProps = parseJsdocTypeProps(tsAst);
         const destructuredProps = parsePropsDestructuring(tsAst);
         const jsdocData = parseJsdocComments(tsAst);
-        props = mergeProps(interfaceProps, destructuredProps, jsdocData);
+        // TS interface wins over JSDoc types when both exist (they shouldn't).
+        const interfaceNames = new Set(interfaceProps.map((p) => p.name));
+        const typedProps = [
+            ...interfaceProps,
+            ...jsdocTypeProps.filter((p) => !interfaceNames.has(p.name)),
+        ];
+        props = mergeProps(typedProps, destructuredProps, jsdocData);
         methods = parseExportedFunctions(tsAst);
         state = parseExportedState(tsAst);
     }
@@ -52,6 +59,71 @@ function parseInterfaceProps(sourceFile) {
     });
     return props;
 }
+// ─── JSDoc-typed props (plain JS components) ───
+/** Props typed via JSDoc: `@type {{ ... }}` on the $props() declaration, or
+ * `@type {Props}` referencing a `@typedef {Object} Props` with `@property` tags. */
+function parseJsdocTypeProps(sourceFile) {
+    const props = [];
+    function fromTypeLiteral(literal) {
+        for (const member of literal.members) {
+            if (ts.isPropertySignature(member) && member.name) {
+                props.push({
+                    name: member.name.getText(sourceFile),
+                    type: member.type ? member.type.getText(sourceFile) : 'unknown',
+                    optional: !!member.questionToken,
+                    description: null,
+                });
+            }
+        }
+    }
+    function fromTypedef(name) {
+        function visit(node) {
+            // ts.getJSDocTags only surfaces the last JSDoc comment on a node;
+            // a standalone @typedef block above the @type one needs the raw list.
+            const jsDocs = node.jsDoc ?? [];
+            for (const tag of jsDocs.flatMap((jd) => [...(jd.tags ?? [])])) {
+                if (ts.isJSDocTypedefTag(tag) &&
+                    tag.name?.getText(sourceFile) === name &&
+                    tag.typeExpression &&
+                    ts.isJSDocTypeLiteral(tag.typeExpression)) {
+                    for (const propTag of tag.typeExpression.jsDocPropertyTags ?? []) {
+                        const comment = ts.getTextOfJSDocComment(propTag.comment);
+                        props.push({
+                            name: propTag.name.getText(sourceFile),
+                            type: propTag.typeExpression
+                                ? propTag.typeExpression.type.getText(sourceFile)
+                                : 'unknown',
+                            optional: propTag.isBracketed,
+                            description: comment ? comment.replace(/^-\s*/, '').trim() : null,
+                        });
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+    }
+    function visit(node) {
+        if (ts.isVariableDeclaration(node) &&
+            node.initializer &&
+            ts.isCallExpression(node.initializer) &&
+            node.initializer.expression.getText(sourceFile) === '$props' &&
+            ts.isObjectBindingPattern(node.name)) {
+            // The @type tag sits on the enclosing statement; getJSDocType finds it.
+            const typeNode = ts.getJSDocType(node) ?? ts.getJSDocType(node.parent?.parent ?? node);
+            if (typeNode) {
+                if (ts.isTypeLiteralNode(typeNode))
+                    fromTypeLiteral(typeNode);
+                else if (ts.isTypeReferenceNode(typeNode)) {
+                    fromTypedef(typeNode.typeName.getText(sourceFile));
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return props;
+}
 function parsePropsDestructuring(sourceFile) {
     const props = [];
     function visit(node) {
@@ -159,7 +231,8 @@ function mergeProps(interfaceProps, destructuredProps, jsdocData) {
 function classifyProp(name, type) {
     if (name.startsWith('on') && type?.includes('=>'))
         return 'event';
-    if (type?.startsWith('Snippet'))
+    // Matches `Snippet`, `Snippet<[...]>`, and `import('svelte').Snippet`
+    if (type && /(^|\.)Snippet\b/.test(type))
         return 'snippet';
     return 'prop';
 }

package/dist/server/prop-parser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/prop-parser.test.js

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest';
+import { parseComponentSource } from './prop-parser.js';
+function byName(list, name) {
+    const found = list.find((item) => item.name === name);
+    expect(found, `expected to find "${name}"`).toBeDefined();
+    return found;
+}
+describe('TypeScript components (interface Props)', () => {
+    const source = `<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		/** The button label text */
+		label?: string;
+		/** Visual style variant */
+		variant?: 'primary' | 'secondary';
+		count: number;
+		/** Click handler */
+		onclick?: (e: MouseEvent) => void;
+		oneTime?: boolean;
+		children?: Snippet;
+		item?: Snippet<[value: string]>;
+	}
+
+	let { label = 'Button', variant = 'primary', count, onclick, oneTime, children, item }: Props = $props();
+</script>
+
+<button>{label}</button>`;
+    const data = parseComponentSource(source);
+    it('extracts types, defaults, descriptions, and requiredness', () => {
+        const label = byName(data.props, 'label');
+        expect(label.type).toBe('string');
+        expect(label.default).toBe('Button');
+        expect(label.description).toBe('The button label text');
+        expect(label.required).toBe(false);
+        const count = byName(data.props, 'count');
+        expect(count.type).toBe('number');
+        expect(count.default).toBe(null);
+        expect(count.required).toBe(true);
+    });
+    it('classifies events, snippets, and on-prefixed non-functions', () => {
+        expect(byName(data.props, 'onclick').category).toBe('event');
+        expect(byName(data.props, 'oneTime').category).toBe('prop');
+        expect(byName(data.props, 'children').category).toBe('snippet');
+        expect(byName(data.props, 'item').category).toBe('snippet');
+    });
+});
+describe('JS components with @type {{ ... }} annotation', () => {
+    const source = `<script>
+	/** @type {{ label?: string, size?: 'sm' | 'lg', onclick?: (e: MouseEvent) => void }} */
+	let { label = 'Badge', size = 'sm', onclick } = $props();
+</script>
+
+<span>{label}</span>`;
+    const data = parseComponentSource(source);
+    it('extracts types and optionality from the annotation', () => {
+        const label = byName(data.props, 'label');
+        expect(label.type).toBe('string');
+        expect(label.default).toBe('Badge');
+        expect(label.required).toBe(false);
+        expect(byName(data.props, 'size').type).toBe("'sm' | 'lg'");
+    });
+    it('classifies events from JSDoc function types', () => {
+        expect(byName(data.props, 'onclick').category).toBe('event');
+    });
+});
+describe('JS components with @typedef/@property', () => {
+    const source = `<script>
+	/**
+	 * @typedef {Object} Props
+	 * @property {string} [label] - The badge label
+	 * @property {number} count - How many
+	 * @property {() => void} [ondismiss] - Called when dismissed
+	 * @property {import('svelte').Snippet} [children] - Body content
+	 */
+
+	/** @type {Props} */
+	let { label = 'Badge', count, ondismiss, children } = $props();
+</script>
+
+<span>{label}{count}</span>`;
+    const data = parseComponentSource(source);
+    it('extracts types, descriptions, and optionality from @property tags', () => {
+        const label = byName(data.props, 'label');
+        expect(label.type).toBe('string');
+        expect(label.description).toBe('The badge label');
+        expect(label.required).toBe(false);
+        expect(label.default).toBe('Badge');
+        const count = byName(data.props, 'count');
+        expect(count.type).toBe('number');
+        expect(count.description).toBe('How many');
+        expect(count.required).toBe(true);
+    });
+    it('classifies events and imported Snippet types', () => {
+        expect(byName(data.props, 'ondismiss').category).toBe('event');
+        expect(byName(data.props, 'children').category).toBe('snippet');
+    });
+});
+describe('untyped JS components', () => {
+    it('still extracts names and defaults from destructuring', () => {
+        const data = parseComponentSource(`<script>
+	let { label = 'x', flag } = $props();
+</script>`);
+        expect(byName(data.props, 'label').default).toBe('x');
+        expect(byName(data.props, 'label').type).toBe(null);
+        expect(byName(data.props, 'flag').required).toBe(true);
+    });
+});
+describe('methods, state, and CSS custom properties', () => {
+    const source = `<script lang="ts">
+	/** Clears the value */
+	export function clear(): void {}
+
+	/** Current count */
+	export const count = $state(0);
+
+	/**
+	 * @cssvar {color} --bg - Background color
+	 * @cssvar {dimension} --radius - Corner radius
+	 */
+</script>
+
+<style>
+	.x {
+		background: var(--bg, #333);
+		border-radius: var(--radius, 4px);
+		padding: var(--pad, 8px);
+	}
+</style>`;
+    const data = parseComponentSource(source);
+    it('extracts exported functions with descriptions', () => {
+        const clear = byName(data.methods, 'clear');
+        expect(clear.returnType).toBe('void');
+        expect(clear.description).toBe('Clears the value');
+    });
+    it('extracts exported state', () => {
+        expect(byName(data.state, 'count').description).toBe('Current count');
+    });
+    it('extracts CSS vars, merging @cssvar type/description with var() defaults', () => {
+        const bg = byName(data.cssProps, '--bg');
+        expect(bg.type).toBe('color');
+        expect(bg.default).toBe('#333');
+        expect(bg.description).toBe('Background color');
+        const pad = byName(data.cssProps, '--pad');
+        expect(pad.type).toBe(null);
+        expect(pad.default).toBe('8px');
+    });
+});

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

@@ -25,7 +25,8 @@ export function generateIframeComponent(absoluteImports, snippetBody) {
     const importBlock = absoluteImports.length > 0
         ? absoluteImports.join('\n') + '\n'
         : '';
-    return `<script>
+    // lang="ts" so lifted imports may carry type-only syntax (Svelte 5 erases it natively)
+    return `<script lang="ts">
 	${importBlock}import { onMount } from 'svelte';
 
 	let args = $state({});
@@ -68,7 +69,10 @@ export function generateIframeComponent(absoluteImports, snippetBody) {
 </script>
 
 <div id="sdocs-preview">
-	${snippetBody}
+	{#snippet SdocsPreview(args)}
+		${snippetBody}
+	{/snippet}
+	{@render SdocsPreview(args)}
 </div>`;
 }
 /** Convert a CSS path to a Vite-servable URL */
@@ -93,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>
@@ -106,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`;
@@ -140,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/ui/Button/Button.sdoc

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import type { ComponentProps } from 'svelte';
 	import Button from './Button.svelte';
 	import { Icon } from '../Icon/index.js';
 
@@ -9,8 +10,8 @@
 	};
 </script>
 
-{#snippet Default()}
-	<Button>Click me</Button>
+{#snippet Default(args: ComponentProps<typeof Button>)}
+	<Button {...args}>Click me</Button>
 {/snippet}
 
 {#snippet WithLeftIcon()}

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.23",
+  "version": "0.0.26",
   "description": "A lightweight documentation tool for Svelte 5 components",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,8 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "CHANGELOG.md"
   ],
   "peerDependencies": {
     "@sveltejs/vite-plugin-svelte": "*",