sdocs 0.0.41 → 0.0.43

package/CHANGELOG.md

@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.43] - 2026-07-04
+
+### Added
+
+- **`projectSdoc` in `sdocs/language`** — a line-preserving projection of a
+  `.sdoc` file onto a virtual Svelte document: every authored line keeps its
+  exact position, sub-block openers become the same `{#snippet}` wrappers
+  the build generates, PAGE prose stays live with code regions masked, and
+  a trailer past the authored end marks everything as used. This is the
+  foundation of the VS Code extension's sdoc language server.
+
+### Changed
+
+- The Explorer's own UI library docs (`src/lib/ui/*.sdoc`) are converted to
+  the block format.
+
+## [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/language/index.d.ts

@@ -1,2 +1,3 @@
 export { scanSdoc, offsetToPosition, ENTITY_KINDS, SUB_BLOCK_KINDS, type Span, type EntityKind, type SubBlockKind, type AttrValue, type Attrs, type SubBlock, type Entity, type TagBlock, type ScanError, type SdocFile, } from './scanner.js';
+export { projectSdoc, type SdocProjection, type ProjectedLineKind, } from './projection.js';
 export { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, type ArgValue, type PreviewBlock, type ExampleBlock, type DocsEntity, type PageEntity, type LayoutEntity, type SdocEntity, type SdocDocument, } from './parser.js';

package/dist/language/index.js

@@ -1,2 +1,3 @@
 export { scanSdoc, offsetToPosition, ENTITY_KINDS, SUB_BLOCK_KINDS, } from './scanner.js';
+export { projectSdoc, } from './projection.js';
 export { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, } from './parser.js';

package/dist/language/projection.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Line-preserving projection of a .sdoc file into a virtual Svelte document.
+ *
+ * Every authored line keeps its exact (line, column) in the virtual text, so
+ * editor position mapping is the identity function. Block syntax the Svelte
+ * compiler must not see becomes blank lines; sub-block openers are rewritten
+ * IN PLACE to `{#snippet …(args)}` wrappers — byte-compatible with the shape
+ * the build pipeline generates at runtime — and a trailer appended past the
+ * authored end renders every snippet and references previewed components, so
+ * nothing draws unused-import noise. Diagnostics on trailer lines
+ * (line >= sourceLineCount) are generated, never authored.
+ */
+import type { SdocFile } from './scanner.js';
+export type ProjectedLineKind = 'verbatim' | 'blank' | 'wrapper' | 'masked';
+export interface SdocProjection {
+    /** The virtual Svelte document text */
+    text: string;
+    /** Authored line count; virtual lines at or past this are generated */
+    sourceLineCount: number;
+    /** Per authored line: how it was projected */
+    lineKinds: ProjectedLineKind[];
+}
+export declare function projectSdoc(file: SdocFile): SdocProjection;

package/dist/language/projection.js

@@ -0,0 +1,136 @@
+/**
+ * Line-preserving projection of a .sdoc file into a virtual Svelte document.
+ *
+ * Every authored line keeps its exact (line, column) in the virtual text, so
+ * editor position mapping is the identity function. Block syntax the Svelte
+ * compiler must not see becomes blank lines; sub-block openers are rewritten
+ * IN PLACE to `{#snippet …(args)}` wrappers — byte-compatible with the shape
+ * the build pipeline generates at runtime — and a trailer appended past the
+ * authored end renders every snippet and references previewed components, so
+ * nothing draws unused-import noise. Diagnostics on trailer lines
+ * (line >= sourceLineCount) are generated, never authored.
+ */
+function lineStartsOf(source) {
+    const starts = [0];
+    for (let i = 0; i < source.length; i++) {
+        if (source[i] === '\n')
+            starts.push(i + 1);
+    }
+    return starts;
+}
+function lineOfOffset(starts, offset) {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (starts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo;
+}
+/** Mask markdown code so a PAGE body reads as Svelte-safe prose: fence lines
+ * and fence interiors go blank; inline `code` spans are space-overwritten
+ * (column-preserving). Everything else — prose, {expressions}, component
+ * islands — stays verbatim. */
+function maskMarkdownLine(line, state) {
+    const fenceMarker = /^\s*(`{3,}|~{3,})/.test(line);
+    if (fenceMarker) {
+        state.inFence = !state.inFence;
+        return { text: '', masked: true };
+    }
+    if (state.inFence)
+        return { text: '', masked: true };
+    if (!line.includes('`'))
+        return { text: line, masked: false };
+    const text = line.replace(/`[^`]*`/g, (m) => ' '.repeat(m.length));
+    return { text, masked: text !== line };
+}
+export function projectSdoc(file) {
+    const source = file.source;
+    const starts = lineStartsOf(source);
+    const total = starts.length;
+    const out = new Array(total).fill('');
+    const kinds = new Array(total).fill('blank');
+    const copyVerbatim = (span) => {
+        const first = lineOfOffset(starts, span.start);
+        const last = lineOfOffset(starts, Math.max(span.start, span.end - 1));
+        for (let l = first; l <= last; l++) {
+            const end = l + 1 < total ? starts[l + 1] - 1 : source.length;
+            out[l] = source.slice(starts[l], end).replace(/\r$/, '');
+            kinds[l] = 'verbatim';
+        }
+    };
+    if (file.script)
+        copyVerbatim(file.script.span);
+    if (file.style)
+        copyVerbatim(file.style.span);
+    const isTs = /lang\s*=\s*["']ts["']/.test(file.script?.attrsText ?? '');
+    const argsParam = isTs ? '(args: any)' : '(args)';
+    const snippets = [];
+    const componentRefs = new Set();
+    const wrapBlock = (name, openerSpan, bodySpan, closerLineOf, // block span; its end sits on the closer line
+    withArgs, maskBody) => {
+        const openFirst = lineOfOffset(starts, openerSpan.start);
+        const openLast = lineOfOffset(starts, Math.max(openerSpan.start, openerSpan.end - 1));
+        out[openFirst] = `{#snippet ${name}${withArgs ? argsParam : '()'}}`;
+        kinds[openFirst] = 'wrapper';
+        for (let l = openFirst + 1; l <= openLast; l++) {
+            out[l] = '';
+            kinds[l] = 'blank';
+        }
+        if (bodySpan.end > bodySpan.start) {
+            if (maskBody) {
+                const first = lineOfOffset(starts, bodySpan.start);
+                const last = lineOfOffset(starts, Math.max(bodySpan.start, bodySpan.end - 1));
+                const state = { inFence: false };
+                for (let l = first; l <= last; l++) {
+                    const end = l + 1 < total ? starts[l + 1] - 1 : source.length;
+                    const line = source.slice(starts[l], end).replace(/\r$/, '');
+                    const masked = maskMarkdownLine(line, state);
+                    out[l] = masked.text;
+                    kinds[l] = masked.masked ? 'masked' : 'verbatim';
+                }
+            }
+            else {
+                copyVerbatim(bodySpan);
+            }
+        }
+        const closeLine = lineOfOffset(starts, Math.max(closerLineOf.start, closerLineOf.end - 1));
+        out[closeLine] = '{/snippet}';
+        kinds[closeLine] = 'wrapper';
+        snippets.push({ name, withArgs });
+    };
+    file.entities.forEach((entity, e) => {
+        if (entity.kind === 'DOCS') {
+            entity.blocks.forEach((block, b) => {
+                wrapBlock(`__sdocs$${e}_${b}`, block.openerSpan, block.bodySpan, block.span, true, false);
+                const component = block.attrs.component;
+                if (component?.kind === 'expression') {
+                    const name = component.raw.trim();
+                    if (/^[A-Z][A-Za-z0-9_]*$/.test(name))
+                        componentRefs.add(name);
+                }
+            });
+        }
+        else {
+            wrapBlock(`__sdocs$${e}`, entity.openerSpan, entity.bodySpan, entity.span, false, entity.kind === 'PAGE');
+        }
+    });
+    // Trailer: render every snippet and reference previewed components so the
+    // Svelte/TS layer sees everything as used. Lives past the authored end.
+    const trailer = ['{#if false}'];
+    for (const snippet of snippets) {
+        trailer.push(`{@render ${snippet.name}(${snippet.withArgs ? '{}' : ''})}`);
+    }
+    for (const name of componentRefs) {
+        trailer.push(`<${name} />`);
+    }
+    trailer.push('{/if}');
+    return {
+        text: out.join('\n') + '\n' + trailer.join('\n') + '\n',
+        sourceLineCount: total,
+        lineKinds: kinds,
+    };
+}

package/dist/language/projection.test.d.ts

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

package/dist/language/projection.test.js

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { compile } from 'svelte/compiler';
+import { scanSdoc } from './scanner.js';
+import { projectSdoc } from './projection.js';
+const SOURCE = `<script lang="ts">
+	import Tabs from './Tabs.svelte';
+	import Tab from './Tab.svelte';
+	const shared = 1;
+</script>
+
+[DOCS title="Nav / Tabs" description="A tab bar."]
+
+	[preview component={Tabs} args={{ active: 0 }}]
+		<Tabs {...args} active={shared}>x</Tabs>
+	[/preview]
+
+	[example title="Wrapped child"]
+		<Tabs><Tab {...args} /></Tabs>
+	[/example]
+
+[/DOCS]
+
+[PAGE title="Guide"]
+
+	## Heading
+
+	Uses {shared} and <Tabs />.
+
+	\`\`\`svelte
+	<NotReal {broken} />
+	\`\`\`
+
+	Inline \`{code}\` is masked.
+
+[/PAGE]
+
+<style>
+	.x { color: red; }
+</style>
+`;
+describe('projectSdoc', () => {
+    const projection = projectSdoc(scanSdoc(SOURCE));
+    const lines = projection.text.split('\n');
+    const sourceLines = SOURCE.split('\n');
+    it('preserves every authored line position', () => {
+        expect(projection.sourceLineCount).toBe(sourceLines.length);
+        for (let i = 0; i < sourceLines.length; i++) {
+            const kind = projection.lineKinds[i];
+            if (kind === 'verbatim')
+                expect(lines[i]).toBe(sourceLines[i]);
+            if (kind === 'blank')
+                expect(lines[i]).toBe('');
+        }
+    });
+    const at = (needle) => sourceLines.findIndex((l) => l.includes(needle));
+    it('keeps script, style, and bodies verbatim at identical lines', () => {
+        expect(lines[1]).toBe("\timport Tabs from './Tabs.svelte';");
+        expect(lines[at('{...args} active')]).toBe(sourceLines[at('{...args} active')]);
+        expect(lines[at('color: red')]).toContain('color: red');
+    });
+    it('rewrites sub-block openers to snippet wrappers in place', () => {
+        expect(lines[at('[preview')]).toBe('{#snippet __sdocs$0_0(args: any)}');
+        expect(lines[at('[/preview]')]).toBe('{/snippet}');
+        expect(lines[at('[example')]).toBe('{#snippet __sdocs$0_1(args: any)}');
+    });
+    it('blanks entity tags and masks PAGE code while keeping prose live', () => {
+        expect(lines[at('[DOCS')]).toBe('');
+        const proseLine = sourceLines.findIndex((l) => l.includes('Uses {shared}'));
+        expect(lines[proseLine]).toBe(sourceLines[proseLine]);
+        const fenceBody = sourceLines.findIndex((l) => l.includes('NotReal'));
+        expect(lines[fenceBody]).toBe('');
+        const inline = sourceLines.findIndex((l) => l.includes('Inline'));
+        expect(lines[inline]).not.toContain('{code}');
+        expect(lines[inline].length).toBe(sourceLines[inline].length);
+    });
+    it('appends a trailer that renders snippets and references components', () => {
+        const trailer = lines.slice(projection.sourceLineCount).join('\n');
+        expect(trailer).toContain('{@render __sdocs$0_0({})}');
+        expect(trailer).toContain('{@render __sdocs$1()}');
+        expect(trailer).toContain('<Tabs />');
+    });
+    it('produces text the Svelte compiler accepts', () => {
+        expect(() => compile(projection.text, { generate: false })).not.toThrow();
+    });
+});
+describe('projectSdoc over the real corpus', () => {
+    const dirs = [
+        resolve(__dirname, '../../../../../apps/site/src/lib/ui'),
+        resolve(__dirname, '../../../../../apps/testapp-embedded/src/lib/UI'),
+        resolve(__dirname, '../../../../../apps/testapp-standalone/src'),
+    ];
+    const files = [];
+    for (const dir of dirs) {
+        try {
+            for (const f of readdirSync(dir, { recursive: true })) {
+                if (f.endsWith('.sdoc'))
+                    files.push(resolve(dir, f));
+            }
+        }
+        catch {
+            // corpus dir not present in this checkout
+        }
+    }
+    it('found the corpus', () => {
+        expect(files.length).toBeGreaterThanOrEqual(10);
+    });
+    for (const file of files) {
+        it(`compiles ${file.split('/').slice(-1)[0]}`, () => {
+            const source = readFileSync(file, 'utf-8');
+            const projection = projectSdoc(scanSdoc(source));
+            expect(projection.sourceLineCount).toBe(source.split('\n').length);
+            expect(() => compile(projection.text, { generate: false })).not.toThrow();
+        });
+    }
+});

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('/'));