sdocs 0.0.41 → 0.0.42

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.42] - 2026-07-04
+
+### Changed
+
+- **Breaking: `.sdoc` files are the block format.** A doc file is now
+  `<script>` on top, `[DOCS]`/`[PAGE]`/`[LAYOUT]` entity blocks in the
+  middle, `<style>` at the bottom — the language documented in the site's
+  Language section. Each entity is its own sidebar entry, so one file can
+  hold several. The `export const meta` convention, `{#snippet}` extraction,
+  auto-generated `Default` previews, and the `.page.sdoc`/`.layout.sdoc`
+  filename kinds are gone.
+- **`[DOCS]` holds any number of previews.** Each
+  `[preview component={X} args={{…}}]` is self-contained; several render as
+  tabs, each a fully live panel with its own controls, extracted API tables,
+  and component source. `[example title="…"]` blocks are frozen and render
+  page-level below the tabs.
+- **`[PAGE]` bodies are markdown** — GFM with `{expression}` interpolation
+  and Svelte component islands; code fences and inline code are inert. The
+  table of contents comes from the markdown headings.
+- **Parsing never crashes the dev server.** Doc files parse through the
+  `sdocs/language` scanner; mistakes surface as file:line warnings and the
+  rest of the file keeps working.
+- **Breaking for embedders:** `DocEntry` is reshaped (`previews`/`examples`/
+  `content` replace `snippets`/`componentData`), and preview URLs address
+  entities as `path#slug`.
+
 ## [0.0.41] - 2026-07-04
 
 ### Added

package/dist/explorer/tree-builder.js

@@ -44,9 +44,7 @@ export function buildTree(docs, sidebar) {
         // Create the item node
         const itemPath = [...currentPath, itemName];
         if (kind === 'component') {
-            const examples = doc.snippets
-                ?.filter((s) => s.name !== 'Default')
-                .map((s) => s.name) ?? [];
+            const examples = doc.examples?.map((s) => s.name) ?? [];
             // Check if a folder node with this name already exists (created by a child doc)
             const existing = parent.find((n) => n.name === itemName);
             const componentNode = existing ?? {
@@ -195,7 +193,7 @@ export function findDocByPath(docs, path) {
         // One extra segment → example
         if (segments.length === path.length - 1 && segments.every((s, i) => s === path[i])) {
             const snippetName = path[path.length - 1];
-            const hasSnippet = doc.snippets?.some((s) => s.name === snippetName);
+            const hasSnippet = doc.examples?.some((s) => s.name === snippetName);
             if (hasSnippet) {
                 return { doc, snippetName };
             }

package/dist/explorer/views/ComponentView.svelte

@@ -18,28 +18,40 @@
 	let { doc, snippetName, activeStylesheet }: Props = $props();
 
 	const meta = $derived(doc.meta);
-	const cd = $derived(doc.componentData);
+	const previews = $derived(doc.previews ?? []);
+
+	// Active preview tab (one full live panel per preview)
+	let activeIndex = $state(0);
+	$effect(() => {
+		doc;
+		activeIndex = 0;
+	});
+	const activePreview = $derived(
+		previews.length > 0 ? previews[Math.min(activeIndex, previews.length - 1)] : undefined,
+	);
+
+	const cd = $derived(activePreview?.componentData ?? null);
 	const componentName = $derived(
-		typeof meta.component === 'string'
-			? meta.component
-			: (meta.title ?? '').split('/').pop()?.trim() ?? 'Component',
+		activePreview?.componentName ??
+			((meta.title ?? '').split('/').pop()?.trim() || 'Component'),
+	);
+	const exampleSnippets = $derived(doc.examples ?? []);
+	const focusedSnippet = $derived(
+		snippetName ? exampleSnippets.find((s) => s.name === snippetName) : null,
 	);
-	const snippets = $derived(doc.snippets ?? []);
-	const defaultSnippet = $derived(snippets.find((s) => s.name === 'Default'));
-	const exampleSnippets = $derived(snippets.filter((s) => s.name !== 'Default'));
-	const focusedSnippet = $derived(snippetName ? snippets.find((s) => s.name === snippetName) : null);
 
 	// Props/CSS controls state
 	let propValues = $state<Record<string, unknown>>({});
 	let cssValues = $state<Record<string, string>>({});
 
-	// Live wiring to the default preview: method invocation + exported state values
+	// Live wiring to the active preview: method invocation + exported state values
 	let defaultPreview = $state<{ callMethod: (name: string) => void }>();
 	let liveStateValues = $state<Record<string, unknown>>({});
 
-	// Initialize from meta.args (build new objects to avoid read+write loop)
+	// Initialize from the active preview's args (build new objects to avoid
+	// read+write loop); re-runs on doc and tab change.
 	$effect(() => {
-		propValues = { ...(meta.args ?? {}) };
+		propValues = { ...(activePreview?.args ?? {}) };
 		const newCss: Record<string, string> = {};
 		if (cd?.cssProps) {
 			for (const cp of cd.cssProps) {
@@ -47,6 +59,7 @@
 			}
 		}
 		cssValues = newCss;
+		liveStateValues = {};
 	});
 
 	function handlePropChange(name: string, value: unknown) {
@@ -159,8 +172,8 @@
 		return snippetBody.slice(0, attrsStart) + attrs + closing + snippetBody.slice(tagEnd + 1);
 	}
 
-	// Initial values for diffing (computed once per doc change)
-	const initialProps = $derived(meta.args ?? {});
+	// Initial values for diffing (computed once per doc/tab change)
+	const initialProps = $derived(activePreview?.args ?? {});
 	const initialCss = $derived.by(() => {
 		const css: Record<string, string> = {};
 		if (cd?.cssProps) {
@@ -172,8 +185,8 @@
 	});
 
 	const usageCode = $derived.by(() => {
-		if (defaultSnippet?.body) {
-			return patchSnippetCode(defaultSnippet.body, componentName, propValues, cssValues, initialProps, initialCss);
+		if (activePreview?.snippet.body) {
+			return patchSnippetCode(activePreview.snippet.body, componentName, propValues, cssValues, initialProps, initialCss);
 		}
 		return generateFallbackCode(componentName, propValues, cssValues);
 	});
@@ -198,7 +211,7 @@
 	});
 
 	function handleReset() {
-		propValues = { ...(meta.args ?? {}) };
+		propValues = { ...(activePreview?.args ?? {}) };
 		const newCss: Record<string, string> = {};
 		if (cd?.cssProps) {
 			for (const cp of cd.cssProps) {
@@ -290,19 +303,37 @@
 			{/if}
 		</div>
 
+		{#if previews.length > 1}
+			<div class="sdocs-preview-tabs" role="tablist">
+				{#each previews as preview, i (preview.snippet.slug)}
+					<button
+						class="sdocs-preview-tab"
+						class:active={i === activeIndex}
+						role="tab"
+						aria-selected={i === activeIndex}
+						onclick={() => (activeIndex = i)}
+					>
+						{preview.label}
+					</button>
+				{/each}
+			</div>
+		{/if}
+
 		<div class="sdocs-panels">
 			<!-- Showcase -->
-			{#if defaultSnippet}
-				<div class="sdocs-preview-wrapper">
-					<PreviewFrame
-						bind:this={defaultPreview}
-						src={defaultSnippet.previewUrl ?? ''}
-						props={propValues}
-						cssVars={cssValues}
-						{activeStylesheet}
-						onStateValues={(values) => (liveStateValues = values)}
-					/>
-				</div>
+			{#if activePreview}
+				{#key activePreview.snippet.slug}
+					<div class="sdocs-preview-wrapper">
+						<PreviewFrame
+							bind:this={defaultPreview}
+							src={activePreview.snippet.previewUrl ?? ''}
+							props={propValues}
+							cssVars={cssValues}
+							{activeStylesheet}
+							onStateValues={(values) => (liveStateValues = values)}
+						/>
+					</div>
+				{/key}
 
 				<CollapsiblePanel title="Preview Code" defaultExpanded={false}>
 					<div class="sdocs-code-block">
@@ -414,11 +445,11 @@
 			{/each}
 		{/if}
 
-		{#if doc.highlightedSource}
+		{#if activePreview?.highlightedSource}
 			<hr class="sdocs-divider" />
 			<div class="sdocs-panels">
 				<CollapsiblePanel title="Component Source" defaultExpanded={false}>
-					<div class="sdocs-code-block">{@html doc.highlightedSource}</div>
+					<div class="sdocs-code-block">{@html activePreview.highlightedSource}</div>
 				</CollapsiblePanel>
 			</div>
 		{/if}
@@ -476,6 +507,31 @@
 		opacity: 0.4;
 		cursor: default;
 	}
+	.sdocs-preview-tabs {
+		display: flex;
+		gap: 4px;
+		margin-bottom: 12px;
+		border-bottom: 1px solid var(--color-base-200);
+	}
+	.sdocs-preview-tab {
+		padding: 7px 14px;
+		border: none;
+		border-bottom: 2px solid transparent;
+		background: none;
+		font: inherit;
+		font-size: 13px;
+		font-weight: 500;
+		color: var(--color-base-500);
+		cursor: pointer;
+	}
+	.sdocs-preview-tab:hover {
+		color: var(--color-base-800);
+	}
+	.sdocs-preview-tab.active {
+		color: var(--color-base-900);
+		border-bottom-color: var(--color-accent-500, var(--color-base-900));
+		font-weight: 600;
+	}
 	.sdocs-view-header {
 		margin-bottom: 24px;
 	}

package/dist/explorer/views/LayoutView.svelte

@@ -9,7 +9,7 @@
 
 	let { doc, activeStylesheet }: Props = $props();
 
-	const contentSnippet = $derived(doc.snippets?.[0]);
+	const contentSnippet = $derived(doc.content);
 </script>
 
 <div class="sdocs-layout-view">

package/dist/explorer/views/PageView.svelte

@@ -10,7 +10,7 @@
 	let { doc, activeStylesheet }: Props = $props();
 
 	const meta = $derived(doc.meta);
-	const contentSnippet = $derived(doc.snippets?.[0]);
+	const contentSnippet = $derived(doc.content);
 	const toc = $derived(doc.toc ?? []);
 
 	function scrollToHeading(id: string) {

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { sdocsPlugin } from './vite.js';
-export type { SdocsConfig, ResolvedSdocsConfig, SdocMeta, DocEntry, ParsedProp, ParsedMethod, ParsedState, ParsedCssProp, ComponentData, ExtractedSnippet, } from './types.js';
+export type { SdocsConfig, ResolvedSdocsConfig, SdocMeta, DocEntry, ParsedProp, ParsedMethod, ParsedState, ParsedCssProp, ComponentData, ExtractedSnippet, PreviewEntry, TocHeading, } from './types.js';

package/dist/server/app-gen.js

@@ -3,9 +3,10 @@ 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 { encodeDocPath, setDocPathRoot } from './snippet-compiler.js';
+import { discoverDocFiles } from './discovery.js';
+import { parseSdoc } from '../language/index.js';
+import { planEntitySnippets } from './doc-model.js';
+import { encodeEntityId, setDocPathRoot } from './snippet-compiler.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /** Source Explorer directory in the installed package (dist/explorer, next to dist/server) */
 function getExplorerSourceDir() {
@@ -141,23 +142,19 @@ function generatePreviewHtml(iframeVirtualId, css) {
 </body>
 </html>`;
 }
-/** Discover doc files and extract snippet names (lightweight, no highlighting) */
+/** Discover doc files and plan snippet slugs per entity (lightweight, no highlighting) */
 async function discoverSnippets(config, cwd) {
     const files = await discoverDocFiles(config.include, cwd);
     const results = [];
     for (const filePath of files) {
         const source = await readFile(filePath, 'utf-8');
-        const kind = getSdocKind(filePath);
-        if (kind === 'page' || kind === 'layout') {
-            results.push({ filePath, snippetNames: ['Content'] });
-        }
-        else {
-            const snippets = extractSnippets(source);
-            const names = snippets.map((s) => s.name);
-            if (!hasDefaultSnippet(snippets)) {
-                names.unshift('Default');
-            }
-            results.push({ filePath, snippetNames: names });
+        const doc = parseSdoc(source);
+        for (const entity of doc.entities) {
+            results.push({
+                filePath,
+                entitySlug: entity.slug,
+                snippetSlugs: planEntitySnippets(entity).map((s) => s.slug),
+            });
         }
     }
     return results;
@@ -186,15 +183,15 @@ export async function generateBuildFiles(config, cwd) {
     };
     // Discover snippets and generate preview HTML pages
     const docSnippets = await discoverSnippets(config, cwd);
-    for (const { filePath, snippetNames } of docSnippets) {
-        const encoded = encodeDocPath(filePath);
-        for (const snippetName of snippetNames) {
-            const iframeId = `/@sdocs/iframe/${encoded}/${snippetName}.svelte`;
+    for (const { filePath, entitySlug, snippetSlugs } of docSnippets) {
+        const encoded = encodeEntityId(filePath, entitySlug);
+        for (const snippetSlug of snippetSlugs) {
+            const iframeId = `/@sdocs/iframe/${encoded}/${snippetSlug}.svelte`;
             const previewDir = resolve(sdocsDir, 'previews', encoded);
             await mkdir(previewDir, { recursive: true });
-            const previewPath = resolve(previewDir, `${snippetName}.html`);
+            const previewPath = resolve(previewDir, `${snippetSlug}.html`);
             await writeFile(previewPath, generatePreviewHtml(iframeId, config.css));
-            const inputKey = `preview-${encoded}-${snippetName}`;
+            const inputKey = `preview-${encoded}-${snippetSlug}`;
             inputs[inputKey] = previewPath;
         }
     }

package/dist/server/discovery.d.ts

@@ -1,6 +1,4 @@
 /** Discover all .sdoc files matching the include patterns */
 export declare function discoverDocFiles(include: string[], root: string): Promise<string[]>;
-/** Determine the sdoc kind from the file path */
-export declare function getSdocKind(filePath: string): 'component' | 'page' | 'layout';
 /** Get the absolute path for a relative import */
 export declare function resolveImportPath(importPath: string, fromFile: string): string;

package/dist/server/discovery.js

@@ -8,15 +8,6 @@ export async function discoverDocFiles(include, root) {
     });
     return files.sort();
 }
-/** Determine the sdoc kind from the file path */
-export function getSdocKind(filePath) {
-    const name = filePath.split('/').pop() ?? '';
-    if (name.includes('.page.'))
-        return 'page';
-    if (name.includes('.layout.'))
-        return 'layout';
-    return 'component';
-}
 /** Get the absolute path for a relative import */
 export function resolveImportPath(importPath, fromFile) {
     const dir = fromFile.substring(0, fromFile.lastIndexOf('/'));

package/dist/server/doc-model.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared entity → snippet planning. Both the Vite plugin (URL generation)
+ * and the CLI app-gen (pre-computed rollup inputs) derive snippet slugs
+ * from this module, so build inputs always byte-match plugin output.
+ */
+import { type SdocEntity } from '../language/index.js';
+export type SnippetRole = 'preview' | 'example' | 'content';
+export interface PlannedSnippet {
+    name: string;
+    slug: string;
+    role: SnippetRole;
+    body: string;
+}
+/** URL-safe slug for an example snippet. The 'x-' prefix keeps example
+ * slugs disjoint from preview slugs and 'content'. */
+export declare function exampleSlug(title: string): string;
+/** URL-safe slug for a preview snippet (from its tab label). */
+export declare function previewSlug(label: string): string;
+/** The snippets one entity produces, in order: previews, then examples,
+ * or the single 'content' body for PAGE/LAYOUT. */
+export declare function planEntitySnippets(entity: SdocEntity): PlannedSnippet[];
+/** Extract import statements from the file-level script content. */
+export declare function extractImports(scriptContent: string): string[];
+/** Resolve a preview's component identifier to an absolute .svelte path via
+ * the file's imports. Returns null when the identifier isn't imported. */
+export declare function resolveComponentImport(componentName: string, imports: string[], docFilePath: string): string | null;

package/dist/server/doc-model.js

@@ -0,0 +1,58 @@
+/**
+ * Shared entity → snippet planning. Both the Vite plugin (URL generation)
+ * and the CLI app-gen (pre-computed rollup inputs) derive snippet slugs
+ * from this module, so build inputs always byte-match plugin output.
+ */
+import { resolve, dirname } from 'node:path';
+import { slugifyTitle } from '../language/index.js';
+/** URL-safe slug for an example snippet. The 'x-' prefix keeps example
+ * slugs disjoint from preview slugs and 'content'. */
+export function exampleSlug(title) {
+    return 'x-' + slugifyTitle(title);
+}
+/** URL-safe slug for a preview snippet (from its tab label). */
+export function previewSlug(label) {
+    return slugifyTitle(label);
+}
+/** The snippets one entity produces, in order: previews, then examples,
+ * or the single 'content' body for PAGE/LAYOUT. */
+export function planEntitySnippets(entity) {
+    if (entity.kind === 'DOCS') {
+        return [
+            ...entity.previews.map((p) => ({
+                name: p.label,
+                slug: previewSlug(p.label),
+                role: 'preview',
+                body: p.body,
+            })),
+            ...entity.examples.map((e) => ({
+                name: e.title,
+                slug: exampleSlug(e.title),
+                role: 'example',
+                body: e.body,
+            })),
+        ];
+    }
+    return [{ name: 'Content', slug: 'content', role: 'content', body: entity.body }];
+}
+/** Extract import statements from the file-level script content. */
+export function extractImports(scriptContent) {
+    const imports = [];
+    const regex = /^\s*import\s+.+$/gm;
+    let match;
+    while ((match = regex.exec(scriptContent)) !== null) {
+        imports.push(match[0].trim());
+    }
+    return imports;
+}
+/** Resolve a preview's component identifier to an absolute .svelte path via
+ * the file's imports. Returns null when the identifier isn't imported. */
+export function resolveComponentImport(componentName, imports, docFilePath) {
+    for (const imp of imports) {
+        const match = imp.match(new RegExp(`import\\s+${componentName}\\s+from\\s+['"](.+?)['"]`));
+        if (match) {
+            return resolve(dirname(docFilePath), match[1]);
+        }
+    }
+    return null;
+}

package/dist/server/page-markdown.d.ts

@@ -0,0 +1,15 @@
+/**
+ * [PAGE] body transform: markdown-first with Svelte conveniences.
+ *
+ * The body is CommonMark/GFM; prose passes through untouched so
+ * `{expression}` interpolation and `<Component />` islands compile in the
+ * generated Svelte preview. Code fences and inline code are INERT: they are
+ * highlighted (fences) or wrapped (inline) at transform time with `{` and
+ * `}` escaped, so nothing inside code ever interpolates.
+ */
+import type { TocHeading } from '../types.js';
+export interface RenderedPage {
+    html: string;
+    toc: TocHeading[];
+}
+export declare function renderPageMarkdown(source: string): Promise<RenderedPage>;

package/dist/server/page-markdown.js

@@ -0,0 +1,104 @@
+/**
+ * [PAGE] body transform: markdown-first with Svelte conveniences.
+ *
+ * The body is CommonMark/GFM; prose passes through untouched so
+ * `{expression}` interpolation and `<Component />` islands compile in the
+ * generated Svelte preview. Code fences and inline code are INERT: they are
+ * highlighted (fences) or wrapped (inline) at transform time with `{` and
+ * `}` escaped, so nothing inside code ever interpolates.
+ */
+import { Marked } from 'marked';
+import { highlight } from './highlighter.js';
+function slugify(text) {
+    return (text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, '')
+        .trim()
+        .replace(/[\s_]+/g, '-') || 'section');
+}
+/** Make markup Svelte-inert: braces never interpolate. */
+function escapeBraces(html) {
+    return html.replace(/\{/g, '&#123;').replace(/\}/g, '&#125;');
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+function plainText(tokens) {
+    let out = '';
+    for (const token of tokens) {
+        if ('tokens' in token && token.tokens?.length)
+            out += plainText(token.tokens);
+        else if ('text' in token)
+            out += token.text;
+    }
+    return out;
+}
+export async function renderPageMarkdown(source) {
+    const toc = [];
+    const usedIds = new Set();
+    const headingIds = new WeakMap();
+    const fenceHtml = new WeakMap();
+    const marked = new Marked({ gfm: true });
+    const tokens = marked.lexer(source);
+    const walk = (list) => {
+        for (const token of list) {
+            if (token.type === 'heading') {
+                const text = plainText(token.tokens ?? []);
+                const baseId = slugify(text);
+                let id = baseId;
+                for (let n = 2; usedIds.has(id); n++)
+                    id = `${baseId}-${n}`;
+                usedIds.add(id);
+                headingIds.set(token, id);
+                if (token.depth >= 2 && token.depth <= 4) {
+                    toc.push({ text, level: token.depth, id });
+                }
+            }
+            if ('tokens' in token && token.tokens)
+                walk(token.tokens);
+            if ('items' in token && token.items)
+                walk(token.items);
+        }
+    };
+    walk(tokens);
+    // Highlight fences up front (the renderer hooks below must be sync)
+    for (const token of tokens) {
+        if (token.type === 'code') {
+            const lang = (token.lang ?? '').trim().split(/\s+/)[0] || 'text';
+            try {
+                fenceHtml.set(token, escapeBraces(await highlight(token.text, lang)));
+            }
+            catch {
+                fenceHtml.set(token, `<pre><code>${escapeBraces(escapeHtml(token.text))}</code></pre>`);
+            }
+        }
+    }
+    marked.use({
+        renderer: {
+            heading(token) {
+                const html = this.parser.parseInline(token.tokens);
+                const id = headingIds.get(token);
+                return id
+                    ? `<h${token.depth} id="${id}">${html}</h${token.depth}>\n`
+                    : `<h${token.depth}>${html}</h${token.depth}>\n`;
+            },
+            code(token) {
+                return (fenceHtml.get(token) ??
+                    `<pre><code>${escapeBraces(escapeHtml(token.text))}</code></pre>\n`);
+            },
+            codespan(token) {
+                return `<code>${escapeBraces(escapeHtml(token.text))}</code>`;
+            },
+            // Prose passes through as-is: component islands stay component
+            // tags, {expressions} stay expressions.
+            html(token) {
+                return token.text;
+            }
+        }
+    });
+    return { html: marked.parser(tokens), toc };
+}

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

@@ -4,8 +4,12 @@ export declare function base64urlEncode(str: string): string;
 export declare function base64urlDecode(str: string): string;
 /** Set the root that doc paths are encoded against (the Vite root / staging dir) */
 export declare function setDocPathRoot(root: string): void;
-/** Encode a doc file path for use in URLs and emitted file names */
-export declare function encodeDocPath(filePath: string): string;
+/** Encode a doc entity (file + entity slug) for URLs and emitted file names.
+ * The slug rides inside the token as a '#' fragment so every URL shape keeps
+ * exactly one token path segment. */
+export declare function encodeEntityId(filePath: string, entitySlug: string): string;
+/** The docEntries key for one entity of one file */
+export declare function entityKey(filePath: string, entitySlug: string): string;
 /** Resolve relative imports to absolute paths for use in virtual components */
 export declare function resolveImportsToAbsolute(imports: string[], docFilePath: string): string[];
 /** Generate a virtual Svelte iframe wrapper component for a snippet.
@@ -23,26 +27,22 @@ export interface StaticCssLink {
 }
 /** Generate the HTML page for a preview emitted into a host app's build. */
 export declare function generateStaticPreviewHtml(scriptSrc: string, cssLinks: StaticCssLink[]): string;
+export interface ParsedSnippetId {
+    docFilePath: string;
+    entitySlug: string;
+    snippetSlug: string;
+}
 /** Build the virtual module ID for an iframe wrapper component */
-export declare function iframeVirtualId(docFilePath: string, snippetName: string): string;
+export declare function iframeVirtualId(docFilePath: string, entitySlug: string, snippetSlug: string): string;
 /** Build the preview URL for an iframe HTML page (dev mode) */
-export declare function previewUrl(docFilePath: string, snippetName: string): string;
+export declare function previewUrl(docFilePath: string, entitySlug: string, snippetSlug: string): string;
 /** Build the preview URL for static build output */
-export declare function buildPreviewUrl(docFilePath: string, snippetName: string): string;
+export declare function buildPreviewUrl(docFilePath: string, entitySlug: string, snippetSlug: string): string;
 /** Virtual module ID for a preview's mount script (embedded production builds) */
-export declare function mountVirtualId(docFilePath: string, snippetName: string): string;
+export declare function mountVirtualId(docFilePath: string, entitySlug: string, snippetSlug: string): string;
 /** Parse a mount virtual ID back into its parts */
-export declare function parseMountId(id: string): {
-    docFilePath: string;
-    snippetName: string;
-} | null;
+export declare function parseMountId(id: string): ParsedSnippetId | null;
 /** Parse an iframe virtual ID back into its parts */
-export declare function parseIframeId(id: string): {
-    docFilePath: string;
-    snippetName: string;
-} | null;
+export declare function parseIframeId(id: string): ParsedSnippetId | null;
 /** Parse a preview URL back into its parts */
-export declare function parsePreviewUrl(url: string): {
-    docFilePath: string;
-    snippetName: string;
-} | null;
+export declare function parsePreviewUrl(url: string): ParsedSnippetId | null;