sdocs 0.0.56 → 0.0.57

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.57] - 2026-07-05
+
+### Added
+
+- **`[example]` blocks inside `[PAGE]`.** Pages can now stage real code in
+  the project's context, mid-prose: an example renders in place on an
+  isolated iframe stage that loads the configured `css`, with a collapsed
+  code panel — exactly like an example in `[DOCS]`. Stage attributes
+  (`maxWidth`, `padding`, `direction`, `gap`, `contentX`, `contentY`)
+  cascade from `content.docs`. Titles are required and unique per page;
+  markdown fences shield block syntax, so a fence may show `[example]`
+  without escaping.
+
+### Changed
+
+- **Page prose renders natively in the Explorer**, with the docs app's own
+  typography — no longer inside an iframe that loads the project `css`. The
+  boundary is now crisp: documentation is docs-styled, stages are
+  project-styled. Pages gain real markdown styling (headings, lists, tables,
+  code), direct table-of-contents scrolling, and native text flow. Svelte
+  islands still work and run in the docs context — showcase code belongs in
+  `[example]` blocks.
+- **Embedded hosts pass `pageModules`.** `virtual:sdocs` now exports
+  `pageModules`; forward it to `<Explorer {docs} {cssNames} {pageModules}>`
+  so pages render their content. Hosts that don't pass it show page examples
+  and headers but no body.
+
 ## [0.0.56] - 2026-07-05
 
 ### Added

package/dist/explorer/Explorer.svelte

@@ -19,6 +19,8 @@
 		cssNames?: string[];
 		/** URL prefix for preview pages when the host app is served under a sub-path (e.g. SvelteKit's base). */
 		previewBase?: string;
+		/** Native page components from `virtual:sdocs`, keyed by contentKey. */
+		pageModules?: Record<string, () => Promise<{ default: unknown }>>;
 		sidebarConfig?: {
 			order?: Record<string, string[]>;
 			open?: string[];
@@ -31,6 +33,7 @@
 		icon = 'sdocs',
 		cssNames = [],
 		previewBase = '',
+		pageModules = {},
 		sidebarConfig
 	}: Props = $props();
 
@@ -90,7 +93,7 @@
 	<main class="sdocs-main" class:sdocs-main-fullscreen={sidebarHidden}>
 		{#if resolved}
 			{#if resolved.doc.kind === 'page'}
-				<PageView doc={resolved.doc} {activeStylesheet} />
+				<PageView doc={resolved.doc} {activeStylesheet} {pageModules} />
 			{:else if resolved.doc.kind === 'layout'}
 				<LayoutView doc={resolved.doc} {activeStylesheet} />
 			{:else}

package/dist/explorer/views/PageView.svelte

@@ -1,28 +1,70 @@
 <script lang="ts">
+	import type { Component } from 'svelte';
 	import type { DocEntry } from '../../types.js';
+	import { Icon } from '../../ui/Icon/index.js';
+	import CollapsiblePanel from './CollapsiblePanel.svelte';
 	import PreviewFrame from './PreviewFrame.svelte';
 	import { displayTitle } from '../tree-builder.js';
 
 	interface Props {
 		doc: DocEntry;
 		activeStylesheet?: string;
+		/** Native page components from `virtual:sdocs`, keyed by contentKey. */
+		pageModules?: Record<string, () => Promise<{ default: unknown }>>;
 	}
 
-	let { doc, activeStylesheet }: Props = $props();
+	let { doc, activeStylesheet, pageModules = {} }: Props = $props();
 
 	const meta = $derived(doc.meta);
-	const contentSnippet = $derived(doc.content);
 	const toc = $derived(doc.toc ?? []);
 
+	// The page body compiles to its own component (prose + islands + example
+	// markers); it renders here, natively — sdocs styling, no iframe. Only the
+	// [example] stages load the project's css, each in its own PreviewFrame.
+	let PageComponent = $state<Component | null>(null);
+	let container: HTMLElement | undefined = $state();
+
+	$effect(() => {
+		const load = doc.contentKey ? pageModules[doc.contentKey] : undefined;
+		PageComponent = null;
+		if (!load) return;
+		let stale = false;
+		load().then((mod) => {
+			if (!stale) PageComponent = mod.default as Component;
+		});
+		return () => {
+			stale = true;
+		};
+	});
+
 	function scrollToHeading(id: string) {
-		const iframe = document.querySelector('.sdocs-page-content .sdocs-iframe') as HTMLIFrameElement;
-		if (iframe?.contentWindow) {
-			iframe.contentWindow.postMessage({ type: 'sdocs:scroll-to', id }, '*');
-		}
+		container?.querySelector(`#${CSS.escape(id)}`)?.scrollIntoView({ behavior: 'smooth' });
 	}
 </script>
 
-<div class="sdocs-page-view">
+{#snippet exampleFrame(index: number)}
+	{@const example = doc.examples?.[index]}
+	{#if example}
+		<div class="sdocs-page-example">
+			{#if example.name}
+				<h3 class="sdocs-example-title">
+					<Icon name="bookmark" --w="14px" --h="14px" --fill="var(--color-example-500)" />
+					{example.name}
+				</h3>
+			{/if}
+			<div class="sdocs-panels">
+				<div class="sdocs-preview-wrapper">
+					<PreviewFrame src={example.previewUrl ?? ''} {activeStylesheet} />
+				</div>
+				<CollapsiblePanel title="Code" defaultExpanded={false}>
+					<div class="sdocs-code-block">{@html example.highlightedHtml ?? ''}</div>
+				</CollapsiblePanel>
+			</div>
+		</div>
+	{/if}
+{/snippet}
+
+<div class="sdocs-page-view" style:padding={doc.padding}>
 	<div class="sdocs-page-main" style:max-width={doc.maxWidth}>
 		<!-- Header -->
 		<div class="sdocs-view-header">
@@ -33,11 +75,11 @@
 		</div>
 
 		<!-- Content -->
-		{#if contentSnippet}
-			<div class="sdocs-page-content">
-				<PreviewFrame src={contentSnippet.previewUrl} {activeStylesheet} />
-			</div>
-		{/if}
+		<div class="sdocs-page-content" bind:this={container}>
+			{#if PageComponent}
+				<PageComponent __sdocsExample={exampleFrame} />
+			{/if}
+		</div>
 	</div>
 
 	<!-- Table of Contents -->
@@ -66,7 +108,7 @@
 	.sdocs-page-view {
 		display: flex;
 		gap: 24px;
-		padding: 24px 32px;
+		/* padding comes from the doc entry (config/entity cascade) */
 		font-family: var(--sans);
 	}
 	.sdocs-page-main {
@@ -87,9 +129,145 @@
 		color: var(--color-base-500);
 		margin: 6px 0 0;
 	}
+
+	/* ── Page prose: the docs app's own typography ── */
 	.sdocs-page-content {
-		flex: 1;
+		font-size: 14px;
+		line-height: 1.7;
+		color: var(--color-base-800);
+	}
+	.sdocs-page-content :global(h1),
+	.sdocs-page-content :global(h2),
+	.sdocs-page-content :global(h3),
+	.sdocs-page-content :global(h4),
+	.sdocs-page-content :global(h5),
+	.sdocs-page-content :global(h6) {
+		color: var(--color-base-900);
+		font-weight: 650;
+		line-height: 1.3;
+		margin: 1.6em 0 0.5em;
+		scroll-margin-top: 16px;
+	}
+	.sdocs-page-content :global(h1) { font-size: 22px; }
+	.sdocs-page-content :global(h2) { font-size: 18px; }
+	.sdocs-page-content :global(h3) { font-size: 15px; }
+	.sdocs-page-content :global(h4),
+	.sdocs-page-content :global(h5),
+	.sdocs-page-content :global(h6) { font-size: 14px; }
+	.sdocs-page-content :global(h1:first-child),
+	.sdocs-page-content :global(h2:first-child),
+	.sdocs-page-content :global(h3:first-child) {
+		margin-top: 0;
+	}
+	.sdocs-page-content :global(p) {
+		margin: 0.7em 0;
+	}
+	.sdocs-page-content :global(a) {
+		color: var(--color-action-500, var(--color-base-900));
+		text-decoration: underline;
+		text-underline-offset: 2px;
+	}
+	.sdocs-page-content :global(ul),
+	.sdocs-page-content :global(ol) {
+		margin: 0.7em 0;
+		padding-left: 1.6em;
+	}
+	.sdocs-page-content :global(li) {
+		margin: 0.25em 0;
+	}
+	.sdocs-page-content :global(blockquote) {
+		margin: 0.9em 0;
+		padding: 2px 16px;
+		border-left: 3px solid var(--color-base-200);
+		color: var(--color-base-600);
+	}
+	.sdocs-page-content :global(hr) {
+		border: none;
+		border-top: 1px solid var(--color-base-200);
+		margin: 24px 0;
+	}
+	.sdocs-page-content :global(code) {
+		font-family: var(--mono);
+		font-size: 0.92em;
+	}
+	.sdocs-page-content :global(:not(pre) > code) {
+		background: var(--color-base-100);
+		border-radius: 4px;
+		padding: 1px 5px;
 	}
+	.sdocs-page-content :global(pre) {
+		margin: 0.9em 0;
+		padding: 12px;
+		border-radius: 6px;
+		overflow-x: auto;
+		font-size: 13px;
+		line-height: 1.5;
+		tab-size: 4;
+	}
+	.sdocs-page-content :global(table) {
+		border-collapse: collapse;
+		margin: 0.9em 0;
+	}
+	.sdocs-page-content :global(th),
+	.sdocs-page-content :global(td) {
+		border: 1px solid var(--color-base-200);
+		padding: 6px 12px;
+		text-align: left;
+	}
+	.sdocs-page-content :global(th) {
+		background: var(--color-base-50);
+		font-weight: 600;
+	}
+	.sdocs-page-content :global(img) {
+		max-width: 100%;
+	}
+
+	/* ── Example stages in the page flow ── */
+	.sdocs-page-example {
+		display: flex;
+		flex-direction: column;
+		gap: 8px;
+		margin: 16px 0;
+	}
+	.sdocs-example-title {
+		display: flex;
+		align-items: center;
+		gap: 6px;
+		font-size: 15px;
+		font-weight: 600;
+		color: var(--color-base-800);
+		margin: 0;
+	}
+	.sdocs-panels {
+		display: flex;
+		flex-direction: column;
+		gap: 1px;
+		border: 1px solid var(--color-base-200);
+		background: var(--color-base-200);
+		border-radius: 8px;
+		overflow: hidden;
+	}
+	.sdocs-preview-wrapper {
+		/* stage padding lives inside the iframe (config/block cascade) */
+		background: var(--color-base-0);
+	}
+	.sdocs-code-block {
+		overflow-x: auto;
+		font-size: 13px;
+		line-height: 1.5;
+		tab-size: 4;
+	}
+	.sdocs-code-block :global(pre) {
+		margin: 0;
+		padding: 12px;
+		border-radius: 6px;
+		overflow-x: auto;
+	}
+	.sdocs-code-block :global(code) {
+		font-family: var(--mono);
+	}
+
+	/* ── Table of contents ── */
 	.sdocs-toc {
 		width: 200px;
 		flex-shrink: 0;

package/dist/grammar/sdoc.tmLanguage.json

@@ -244,6 +244,9 @@
 					"while": "(^|\\G)(?!\\s*\\[/PAGE\\]\\s*$)(?:\\t|[ ]{1,4})?",
 					"contentName": "meta.embedded.block.markdown",
 					"patterns": [
+						{
+							"include": "#page-example"
+						},
 						{
 							"include": "#page-svelte-block"
 						},
@@ -570,6 +573,48 @@
 					"include": "source.ts"
 				}
 			]
+		},
+		"page-example": {
+			"name": "meta.block.example.sdoc",
+			"begin": "(^|\\G)\\s*(\\[)(example)\\b(.*)$",
+			"beginCaptures": {
+				"2": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"3": {
+					"name": "entity.name.tag.sdoc"
+				},
+				"4": {
+					"patterns": [
+						{
+							"include": "#attributes"
+						}
+					]
+				}
+			},
+			"end": "(^|\\G)\\s*(\\[/)(example)(\\])\\s*$",
+			"endCaptures": {
+				"2": {
+					"name": "punctuation.definition.tag.begin.sdoc"
+				},
+				"3": {
+					"name": "entity.name.tag.sdoc"
+				},
+				"4": {
+					"name": "punctuation.definition.tag.end.sdoc"
+				}
+			},
+			"patterns": [
+				{
+					"begin": "(^|\\G)",
+					"while": "(^|\\G)(?!\\s*\\[/example\\]\\s*$)",
+					"patterns": [
+						{
+							"include": "source.svelte"
+						}
+					]
+				}
+			]
 		}
 	}
 }

package/dist/language/parser.d.ts

@@ -59,7 +59,11 @@ export interface PageEntity {
     title: string;
     slug: string;
     sizing: Sizing;
+    /** Prose body with each [example] block replaced by a
+     * `{@render __sdocsExample?.(i)}` marker the page renderer resolves. */
     body: string;
+    /** The page's [example] blocks, in marker order */
+    examples: ExampleBlock[];
     bodySpan: Span;
     openerSpan: Span;
     span: Span;

package/dist/language/parser.js

@@ -234,6 +234,25 @@ function parsePreview(block, diagnostics) {
         span: block.span,
     };
 }
+function parseExample(block, seenTitles, owner, diagnostics) {
+    checkAttrs('[example]', block.attrs, SUB_BLOCK_ATTR_RULES.example, block.openerSpan, diagnostics);
+    const title = stringAttr(block.attrs, 'title') ?? '';
+    if (title && seenTitles.has(title)) {
+        diagnostics.push({
+            code: 'duplicate-example-title',
+            message: `Duplicate example title "${title}" — titles are unique within a [${owner}] block.`,
+            span: block.openerSpan,
+        });
+    }
+    seenTitles.add(title);
+    return {
+        title,
+        sizing: sizingOf(block.attrs),
+        body: normalizeBody(block.body),
+        bodySpan: block.bodySpan,
+        span: block.span,
+    };
+}
 function parseDocs(entity, diagnostics) {
     checkAttrs('[DOCS]', entity.attrs, ENTITY_ATTR_RULES.DOCS, entity.openerSpan, diagnostics);
     const previews = [];
@@ -254,23 +273,7 @@ function parseDocs(entity, diagnostics) {
             previews.push(preview);
         }
         else {
-            checkAttrs('[example]', block.attrs, SUB_BLOCK_ATTR_RULES.example, block.openerSpan, diagnostics);
-            const title = stringAttr(block.attrs, 'title') ?? '';
-            if (title && exampleTitles.has(title)) {
-                diagnostics.push({
-                    code: 'duplicate-example-title',
-                    message: `Duplicate example title "${title}" — titles are unique within a [DOCS] block.`,
-                    span: block.openerSpan,
-                });
-            }
-            exampleTitles.add(title);
-            examples.push({
-                title,
-                sizing: sizingOf(block.attrs),
-                body: normalizeBody(block.body),
-                bodySpan: block.bodySpan,
-                span: block.span,
-            });
+            examples.push(parseExample(block, exampleTitles, 'DOCS', diagnostics));
         }
     }
     const title = stringAttr(entity.attrs, 'title') ?? '';
@@ -286,6 +289,47 @@ function parseDocs(entity, diagnostics) {
         span: entity.span,
     };
 }
+/**
+ * Replace each [example] block in a PAGE's raw body with a
+ * `{@render __sdocsExample?.(i)}` marker at the opener's indentation, so the
+ * markdown renderer passes it through verbatim and the Explorer renders the
+ * example's stage in place.
+ */
+function spliceExampleMarkers(entity) {
+    if (entity.blocks.length === 0)
+        return entity.body;
+    let out = '';
+    let from = 0;
+    entity.blocks.forEach((block, i) => {
+        const before = entity.body.slice(from, block.span.start - entity.bodySpan.start);
+        const indent = before.slice(before.lastIndexOf('\n') + 1);
+        out += before.slice(0, before.length - indent.length);
+        out += `${indent}{@render __sdocsExample?.(${i})}`;
+        from = block.span.end - entity.bodySpan.start;
+    });
+    out += entity.body.slice(from);
+    return out;
+}
+function parsePage(entity, diagnostics) {
+    checkAttrs('[PAGE]', entity.attrs, ENTITY_ATTR_RULES.PAGE, entity.openerSpan, diagnostics);
+    const examples = [];
+    const exampleTitles = new Set();
+    for (const block of entity.blocks) {
+        examples.push(parseExample(block, exampleTitles, 'PAGE', diagnostics));
+    }
+    const title = stringAttr(entity.attrs, 'title') ?? '';
+    return {
+        kind: 'PAGE',
+        title,
+        slug: slugifyTitle(title),
+        sizing: sizingOf(entity.attrs),
+        body: normalizeBody(spliceExampleMarkers(entity)),
+        examples,
+        bodySpan: entity.bodySpan,
+        openerSpan: entity.openerSpan,
+        span: entity.span,
+    };
+}
 export function parseSdoc(source) {
     const scanned = scanSdoc(source);
     const diagnostics = [...scanned.errors];
@@ -296,10 +340,14 @@ export function parseSdoc(source) {
         if (entity.kind === 'DOCS') {
             typed = parseDocs(entity, diagnostics);
         }
+        else if (entity.kind === 'PAGE') {
+            typed = parsePage(entity, diagnostics);
+        }
         else {
-            checkAttrs(`[${entity.kind}]`, entity.attrs, ENTITY_ATTR_RULES[entity.kind], entity.openerSpan, diagnostics);
+            checkAttrs('[LAYOUT]', entity.attrs, ENTITY_ATTR_RULES.LAYOUT, entity.openerSpan, diagnostics);
             const title = stringAttr(entity.attrs, 'title') ?? '';
-            const base = {
+            typed = {
+                kind: 'LAYOUT',
                 title,
                 slug: slugifyTitle(title),
                 sizing: sizingOf(entity.attrs),
@@ -308,7 +356,6 @@ export function parseSdoc(source) {
                 openerSpan: entity.openerSpan,
                 span: entity.span,
             };
-            typed = entity.kind === 'PAGE' ? { kind: 'PAGE', ...base } : { kind: 'LAYOUT', ...base };
         }
         if (slugs.has(typed.slug)) {
             diagnostics.push({

package/dist/language/projection.js

@@ -102,6 +102,56 @@ export function projectSdoc(file) {
         kinds[closeLine] = 'wrapper';
         snippets.push({ name, withArgs });
     };
+    /** A PAGE with [example] blocks: the prose regions and each example body
+     * become SIBLING snippets, split in place — the example opener line closes
+     * the running prose snippet and opens the example's, the example closer
+     * does the reverse. Siblings (not nested) so the trailer can render every
+     * one of them, keeping imports used only by examples free of unused noise. */
+    const wrapPageWithExamples = (entity, e) => {
+        const openFirst = lineOfOffset(starts, entity.openerSpan.start);
+        const openLast = lineOfOffset(starts, Math.max(entity.openerSpan.start, entity.openerSpan.end - 1));
+        out[openFirst] = `{#snippet __sdocs$${e}_p0()}`;
+        kinds[openFirst] = 'wrapper';
+        for (let l = openFirst + 1; l <= openLast; l++) {
+            out[l] = '';
+            kinds[l] = 'blank';
+        }
+        snippets.push({ name: `__sdocs$${e}_p0`, withArgs: false });
+        const maskLines = (fromLine, toLine) => {
+            const state = { inFence: false };
+            for (let l = fromLine; l <= toLine; 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';
+            }
+        };
+        let proseFrom = openLast + 1;
+        entity.blocks.forEach((block, b) => {
+            const bOpenFirst = lineOfOffset(starts, block.openerSpan.start);
+            const bOpenLast = lineOfOffset(starts, Math.max(block.openerSpan.start, block.openerSpan.end - 1));
+            maskLines(proseFrom, bOpenFirst - 1);
+            out[bOpenFirst] = `{/snippet}{#snippet __sdocs$${e}_${b}${argsParam}}`;
+            kinds[bOpenFirst] = 'wrapper';
+            for (let l = bOpenFirst + 1; l <= bOpenLast; l++) {
+                out[l] = '';
+                kinds[l] = 'blank';
+            }
+            if (block.bodySpan.end > block.bodySpan.start)
+                copyVerbatim(block.bodySpan);
+            const bClose = lineOfOffset(starts, Math.max(block.span.start, block.span.end - 1));
+            out[bClose] = `{/snippet}{#snippet __sdocs$${e}_p${b + 1}()}`;
+            kinds[bClose] = 'wrapper';
+            snippets.push({ name: `__sdocs$${e}_${b}`, withArgs: true });
+            snippets.push({ name: `__sdocs$${e}_p${b + 1}`, withArgs: false });
+            proseFrom = bClose + 1;
+        });
+        const closeLine = lineOfOffset(starts, Math.max(entity.span.start, entity.span.end - 1));
+        maskLines(proseFrom, closeLine - 1);
+        out[closeLine] = '{/snippet}';
+        kinds[closeLine] = 'wrapper';
+    };
     file.entities.forEach((entity, e) => {
         if (entity.kind === 'DOCS') {
             entity.blocks.forEach((block, b) => {
@@ -114,6 +164,9 @@ export function projectSdoc(file) {
                 }
             });
         }
+        else if (entity.kind === 'PAGE' && entity.blocks.length > 0) {
+            wrapPageWithExamples(entity, e);
+        }
         else {
             wrapBlock(`__sdocs$${e}`, entity.openerSpan, entity.bodySpan, entity.span, false, entity.kind === 'PAGE');
         }

package/dist/language/scanner.d.ts

@@ -3,7 +3,8 @@
  *
  * A .sdoc file is: optional <script> at the top, entity blocks in the
  * middle ([DOCS] / [PAGE] / [LAYOUT], with lowercase sub-blocks [preview] /
- * [example] inside [DOCS]), optional <style> at the bottom.
+ * [example] inside [DOCS] and [example] inside [PAGE]), optional <style>
+ * at the bottom.
  *
  * The scanner is line-anchored and non-balancing: tags are recognized only
  * at the start of a line and only where the current state allows them, so
@@ -46,9 +47,10 @@ export interface SubBlock {
 export interface Entity {
     kind: EntityKind;
     attrs: Attrs;
-    /** DOCS: sub-blocks. PAGE/LAYOUT: always empty. */
+    /** DOCS: preview/example sub-blocks. PAGE: example sub-blocks. LAYOUT: always empty. */
     blocks: SubBlock[];
-    /** PAGE/LAYOUT: the raw body. DOCS: '' (body text between blocks is an error). */
+    /** PAGE/LAYOUT: the raw body (for PAGE it includes any [example] blocks,
+     * addressable via their spans). DOCS: '' (body text between blocks is an error). */
     body: string;
     bodySpan: Span;
     openerSpan: Span;

package/dist/language/scanner.js

@@ -3,7 +3,8 @@
  *
  * A .sdoc file is: optional <script> at the top, entity blocks in the
  * middle ([DOCS] / [PAGE] / [LAYOUT], with lowercase sub-blocks [preview] /
- * [example] inside [DOCS]), optional <style> at the bottom.
+ * [example] inside [DOCS] and [example] inside [PAGE]), optional <style>
+ * at the bottom.
  *
  * The scanner is line-anchored and non-balancing: tags are recognized only
  * at the start of a line and only where the current state allows them, so
@@ -381,6 +382,88 @@ export function scanSdoc(source) {
         entity.span.end = source.length;
         return lines.length;
     }
+    /** Scan the inside of a [PAGE] entity until its closer: prose lines are
+     * body text, [example] openers capture sub-blocks. Lines inside markdown
+     * code fences are always prose, so a fence may show block syntax without
+     * escaping. The body keeps the raw text of the whole range — example
+     * blocks included — so consumers can splice by span. */
+    function scanPageBody(startLi, entity) {
+        const bodyStart = startLi < lines.length ? lines[startLi].start : source.length;
+        let bodyEnd = bodyStart;
+        let inFence = false;
+        let i = startLi;
+        while (i < lines.length) {
+            const line = lines[i];
+            const trimmed = line.text.trim();
+            if (/^(`{3,}|~{3,})/.test(trimmed)) {
+                inFence = !inFence;
+                bodyEnd = line.end;
+                i++;
+                continue;
+            }
+            if (inFence) {
+                if (trimmed !== '')
+                    bodyEnd = line.end;
+                i++;
+                continue;
+            }
+            if (trimmed === '[/PAGE]') {
+                const tagStart = line.start + line.text.indexOf('[/PAGE]');
+                entity.body = source.slice(bodyStart, Math.max(bodyStart, bodyEnd));
+                entity.bodySpan = { start: bodyStart, end: Math.max(bodyStart, bodyEnd) };
+                entity.span.end = tagStart + '[/PAGE]'.length;
+                return i + 1;
+            }
+            const token = tagToken(trimmed);
+            if (token && !token.closer && token.name === 'example') {
+                const opener = scanOpener(i, token.name.length);
+                if (!opener)
+                    return lines.length;
+                const captured = captureBody(opener.nextLi, '[/example]');
+                if (!captured) {
+                    errors.push({
+                        code: 'unclosed-block',
+                        message: 'Missing [/example].',
+                        span: opener.openerSpan,
+                    });
+                    return lines.length;
+                }
+                entity.blocks.push({
+                    kind: 'example',
+                    attrs: opener.attrs,
+                    body: captured.body,
+                    bodySpan: captured.bodySpan,
+                    openerSpan: opener.openerSpan,
+                    span: { start: opener.openerSpan.start, end: captured.closerSpan.end },
+                });
+                bodyEnd = captured.closerSpan.end;
+                i = captured.nextLi;
+                continue;
+            }
+            if (token && !token.closer && token.name === 'preview') {
+                errors.push({
+                    code: 'unknown-tag',
+                    message: '[preview] is only valid inside [DOCS] — pages showcase with [example].',
+                    span: { start: line.start + line.text.indexOf('['), end: line.end },
+                });
+                i++;
+                continue;
+            }
+            // Everything else — prose, markdown, islands, stray brackets — is body.
+            if (trimmed !== '')
+                bodyEnd = line.end;
+            i++;
+        }
+        errors.push({
+            code: 'unclosed-block',
+            message: 'Missing [/PAGE].',
+            span: entity.openerSpan,
+        });
+        entity.body = source.slice(bodyStart);
+        entity.bodySpan = { start: bodyStart, end: source.length };
+        entity.span.end = source.length;
+        return lines.length;
+    }
     // ---- main loop over top-level lines ----
     while (li < lines.length) {
         const line = lines[li];
@@ -459,6 +542,9 @@ export function scanSdoc(source) {
             if (token.name === 'DOCS') {
                 li = scanDocsBody(opener.nextLi, entity);
             }
+            else if (token.name === 'PAGE') {
+                li = scanPageBody(opener.nextLi, entity);
+            }
             else {
                 const captured = captureBody(opener.nextLi, `[/${token.name}]`);
                 if (!captured) {
@@ -491,7 +577,9 @@ export function scanSdoc(source) {
         if (token && !token.closer && isSubBlockKind(token.name)) {
             errors.push({
                 code: 'block-outside-entity',
-                message: `[${token.name}] is only valid inside a [DOCS] entity.`,
+                message: token.name === 'example'
+                    ? '[example] is only valid inside a [DOCS] or [PAGE] entity.'
+                    : '[preview] is only valid inside a [DOCS] entity.',
                 span,
             });
             li++;

package/dist/server/app-gen.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import { discoverDocFiles } from './discovery.js';
 import { parseSdoc } from '../language/index.js';
-import { planEntitySnippets } from './doc-model.js';
+import { planIframeSnippets } from './doc-model.js';
 import { encodeEntityId, setDocPathRoot } from './snippet-compiler.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -107,7 +107,7 @@ function generateIndexHtml(title) {
 /** Generate the entry.js that mounts the Explorer */
 function generateEntryJs(config) {
     return `import { mount } from 'svelte';
-import { docs, cssNames } from 'virtual:sdocs';
+import { docs, cssNames, pageModules } from 'virtual:sdocs';
 import Explorer from './explorer/Explorer.svelte';
 
 mount(Explorer, {
@@ -115,6 +115,7 @@ mount(Explorer, {
 	props: {
 		docs,
 		cssNames,
+		pageModules,
 		logo: ${JSON.stringify(config.logo)},
 		icon: ${JSON.stringify(config.icon)},
 		sidebarConfig: ${JSON.stringify(config.sidebar)},
@@ -178,7 +179,8 @@ async function discoverSnippets(config, cwd) {
             results.push({
                 filePath,
                 entitySlug: entity.slug,
-                snippetSlugs: planEntitySnippets(entity).map((s) => s.slug),
+                // Iframe pages only: a PAGE's content compiles natively in the Explorer.
+                snippetSlugs: planIframeSnippets(entity).map((s) => s.slug),
             });
         }
     }

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

@@ -16,9 +16,15 @@ export interface PlannedSnippet {
 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. */
+/** The snippets one entity produces, in order: previews then examples for
+ * DOCS, the 'content' body then examples for PAGE, the single 'content'
+ * body for LAYOUT. A PAGE's content renders natively in the Explorer — it
+ * is never served as an iframe page (see planIframeSnippets). */
 export declare function planEntitySnippets(entity: SdocEntity): PlannedSnippet[];
+/** The snippets of an entity that are served as iframe preview pages:
+ * everything except a PAGE's content (which references the Explorer-provided
+ * `__sdocsExample` snippet and only compiles there). */
+export declare function planIframeSnippets(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

package/dist/server/doc-model.js

@@ -14,9 +14,17 @@ export function exampleSlug(title) {
 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. */
+/** The snippets one entity produces, in order: previews then examples for
+ * DOCS, the 'content' body then examples for PAGE, the single 'content'
+ * body for LAYOUT. A PAGE's content renders natively in the Explorer — it
+ * is never served as an iframe page (see planIframeSnippets). */
 export function planEntitySnippets(entity) {
+    const example = (e) => ({
+        name: e.title,
+        slug: exampleSlug(e.title),
+        role: 'example',
+        body: e.body,
+    });
     if (entity.kind === 'DOCS') {
         return [
             ...entity.previews.map((p) => ({
@@ -25,15 +33,20 @@ export function planEntitySnippets(entity) {
                 role: 'preview',
                 body: p.body,
             })),
-            ...entity.examples.map((e) => ({
-                name: e.title,
-                slug: exampleSlug(e.title),
-                role: 'example',
-                body: e.body,
-            })),
+            ...entity.examples.map(example),
         ];
     }
-    return [{ name: 'Content', slug: 'content', role: 'content', body: entity.body }];
+    const content = { name: 'Content', slug: 'content', role: 'content', body: entity.body };
+    if (entity.kind === 'PAGE') {
+        return [content, ...entity.examples.map(example)];
+    }
+    return [content];
+}
+/** The snippets of an entity that are served as iframe preview pages:
+ * everything except a PAGE's content (which references the Explorer-provided
+ * `__sdocsExample` snippet and only compiles there). */
+export function planIframeSnippets(entity) {
+    return planEntitySnippets(entity).filter((s) => !(entity.kind === 'PAGE' && s.role === 'content'));
 }
 /** Extract import statements from the file-level script content. */
 export function extractImports(scriptContent) {

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

@@ -31,6 +31,13 @@ export declare function generateIframeComponent(scriptPrelude: string, snippetBo
     contentX?: string;
     contentY?: string;
 }): string;
+/**
+ * Generate the Svelte component for a [PAGE] body, rendered natively inside
+ * the Explorer (sdocs styling — the project's css never loads here). Prose
+ * arrives as rendered markdown, islands verbatim; `{@render __sdocsExample?.(i)}`
+ * markers render the example stages the Explorer passes in as a snippet prop.
+ */
+export declare function generatePageComponent(scriptPrelude: string, renderedBody: string): string;
 /** 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) */
@@ -53,6 +60,13 @@ export declare function iframeVirtualId(docFilePath: string, entitySlug: 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, entitySlug: string, snippetSlug: string): string;
+/** Virtual module ID for a PAGE entity's native content component */
+export declare function pageVirtualId(docFilePath: string, entitySlug: string): string;
+/** Parse a page virtual ID back into its parts */
+export declare function parsePageId(id: string): {
+    docFilePath: string;
+    entitySlug: string;
+} | null;
 /** Virtual module ID for a preview's mount script (embedded production builds) */
 export declare function mountVirtualId(docFilePath: string, entitySlug: string, snippetSlug: string): string;
 /** Parse a mount virtual ID back into its parts */

package/dist/server/snippet-compiler.js

@@ -205,6 +205,25 @@ ${stateBroadcast}
 	{@render SdocsPreview(args)}
 </div>`;
 }
+/**
+ * Generate the Svelte component for a [PAGE] body, rendered natively inside
+ * the Explorer (sdocs styling — the project's css never loads here). Prose
+ * arrives as rendered markdown, islands verbatim; `{@render __sdocsExample?.(i)}`
+ * markers render the example stages the Explorer passes in as a snippet prop.
+ */
+export function generatePageComponent(scriptPrelude, renderedBody) {
+    const importBlock = scriptPrelude.trim() ? scriptPrelude.trim() + '\n' : '';
+    // lang="ts" so lifted imports may carry type-only syntax
+    return `<script lang="ts">
+	${importBlock}
+	let { __sdocsExample } = $props();
+</script>
+
+<div class="sdocs-page-body">
+${renderedBody}
+</div>
+`;
+}
 /** Convert a CSS path to a Vite-servable URL */
 function normalizeCssHref(href) {
     if (href.startsWith('http'))
@@ -290,6 +309,17 @@ export function previewUrl(docFilePath, entitySlug, snippetSlug) {
 export function buildPreviewUrl(docFilePath, entitySlug, snippetSlug) {
     return `/previews/${encodeEntityId(docFilePath, entitySlug)}/${snippetSlug}.html`;
 }
+/** Virtual module ID for a PAGE entity's native content component */
+export function pageVirtualId(docFilePath, entitySlug) {
+    return `/@sdocs/page/${encodeEntityId(docFilePath, entitySlug)}.svelte`;
+}
+/** Parse a page virtual ID back into its parts */
+export function parsePageId(id) {
+    const match = id.match(/^\/@sdocs\/page\/([^/]+)\.svelte$/);
+    if (!match)
+        return null;
+    return decodeEntityId(match[1]);
+}
 /** Virtual module ID for a preview's mount script (embedded production builds) */
 export function mountVirtualId(docFilePath, entitySlug, snippetSlug) {
     return `/@sdocs/mount/${encodeEntityId(docFilePath, entitySlug)}/${snippetSlug}.js`;

package/dist/types.d.ts

@@ -176,7 +176,7 @@ export interface DocEntry {
     meta: SdocMeta;
     /** Live previews (component kind; empty otherwise) */
     previews: PreviewEntry[];
-    /** Frozen examples (component kind; empty otherwise) */
+    /** Frozen examples (component and page kinds; empty otherwise) */
     examples: ExtractedSnippet[];
     /** The rendered body (page/layout kind; null otherwise) */
     content: ExtractedSnippet | null;
@@ -184,6 +184,10 @@ export interface DocEntry {
     toc?: TocHeading[];
     /** Resolved content-column max width (component and page kinds) */
     maxWidth?: string;
+    /** Resolved page padding (pages only) */
+    padding?: string;
     /** Resolved table-of-contents visibility (pages only) */
     showToc?: boolean;
+    /** Key into the virtual module's pageModules map (pages only) */
+    contentKey?: string;
 }

package/dist/vite.js

@@ -6,18 +6,20 @@ import { parseSdoc, offsetToPosition } from './language/index.js';
 import { planEntitySnippets, extractImports, resolveComponentImport, } from './server/doc-model.js';
 import { renderPageMarkdown } from './server/page-markdown.js';
 import { highlight, disposeHighlighter } from './server/highlighter.js';
-import { parseIframeId, parseMountId, parsePreviewUrl, resolveScriptImports, generateIframeComponent, generateMountScript, generatePreviewHtml, generateStaticPreviewHtml, iframeVirtualId, mountVirtualId, previewUrl, buildPreviewUrl, encodeEntityId, entityKey, setDocPathRoot, } from './server/snippet-compiler.js';
+import { parseIframeId, parseMountId, parsePageId, parsePreviewUrl, resolveScriptImports, generateIframeComponent, generateMountScript, generatePageComponent, generatePreviewHtml, generateStaticPreviewHtml, iframeVirtualId, mountVirtualId, pageVirtualId, previewUrl, buildPreviewUrl, encodeEntityId, entityKey, setDocPathRoot, } 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/';
-/** Every renderable snippet of an entry, in order. */
+const PAGE_PREFIX = '/@sdocs/page/';
+/** Every iframe-served snippet of an entry, in order. A PAGE's content
+ * renders natively in the Explorer (via pageModules), never as an iframe. */
 function allSnippets(entry) {
     return [
         ...entry.previews.map((p) => p.snippet),
         ...entry.examples,
-        ...(entry.content ? [entry.content] : []),
+        ...(entry.content && entry.kind !== 'page' ? [entry.content] : []),
     ];
 }
 export function sdocsPlugin(userConfig) {
@@ -206,6 +208,8 @@ export function sdocsPlugin(userConfig) {
                 return '\0' + id;
             if (id.startsWith(MOUNT_PREFIX))
                 return '\0' + id;
+            if (id.startsWith(PAGE_PREFIX))
+                return '\0' + id;
         },
         load(id) {
             if (id === RESOLVED_VIRTUAL_ID) {
@@ -230,6 +234,17 @@ export function sdocsPlugin(userConfig) {
                 const stateNames = (preview?.componentData?.state ?? []).map((s) => s.name);
                 return generateIframeComponent(scriptPrelude, snippet.body, stateNames, preview?.componentName ?? undefined, snippet.stage);
             }
+            // Virtual native content component for a PAGE entity
+            if (id.startsWith('\0' + PAGE_PREFIX)) {
+                const parsed = parsePageId(id.slice(1));
+                if (!parsed)
+                    return null;
+                const entry = docEntries.get(entityKey(parsed.docFilePath, parsed.entitySlug));
+                if (!entry?.content)
+                    return null;
+                const scriptPrelude = docScriptCache.get(parsed.docFilePath) ?? '';
+                return generatePageComponent(scriptPrelude, entry.content.body);
+            }
             // Virtual mount script for an emitted preview page
             if (id.startsWith('\0' + MOUNT_PREFIX)) {
                 const parsed = parseMountId(id.slice(1));
@@ -363,11 +378,31 @@ export function sdocsPlugin(userConfig) {
                 }
             }
             else if (entity.kind === 'PAGE') {
+                // The page body renders natively in the Explorer; only its
+                // [example] blocks are staged in iframes (with the project css),
+                // cascading block attributes over the content.docs stage defaults.
                 const rendered = await renderPageMarkdown(entity.body);
                 snippets[0].body = rendered.html;
-                snippets[0].stage = stageOf();
                 entry.content = snippets[0];
                 entry.toc = rendered.toc;
+                entry.padding = entity.sizing.padding ?? config.content.page.padding;
+                entry.contentKey = encodeEntityId(filePath, entity.slug);
+                entry.examples = snippets.filter((s) => s.role === 'example');
+                entity.examples.forEach((example, i) => {
+                    if (entry.examples[i]) {
+                        entry.examples[i].stage = {
+                            maxWidth: example.sizing.maxWidth ?? '100%',
+                            padding: example.sizing.padding ?? config.content.docs.padding,
+                            direction: example.sizing.direction ?? config.content.docs.direction,
+                            gap: example.sizing.gap ?? config.content.docs.gap,
+                            contentX: example.sizing.contentX ?? config.content.docs.contentX,
+                            contentY: example.sizing.contentY ?? config.content.docs.contentY,
+                        };
+                    }
+                });
+                for (const example of entry.examples) {
+                    example.highlightedHtml = await highlight(example.body);
+                }
             }
             else {
                 snippets[0].stage = stageOf();
@@ -396,16 +431,26 @@ export function sdocsPlugin(userConfig) {
             meta: e.meta,
             previews: e.previews.map((p) => ({ ...p, snippet: withUrl(e, p.snippet) })),
             examples: e.examples.map((s) => withUrl(e, s)),
-            content: e.content ? withUrl(e, e.content) : null,
+            // Page content renders natively (no iframe URL); see pageModules below.
+            content: e.content ? (e.kind === 'page' ? e.content : withUrl(e, e.content)) : null,
             toc: e.toc,
             maxWidth: e.maxWidth,
+            padding: e.padding,
             showToc: e.showToc,
+            contentKey: e.contentKey,
         }));
         // Extract named CSS stylesheet names (empty array if single string or null)
         const cssNames = config.css && typeof config.css === 'object'
             ? Object.keys(config.css)
             : [];
-        return `export const docs = ${JSON.stringify(data)};\nexport const cssNames = ${JSON.stringify(cssNames)};\nexport default docs;`;
+        // Native page components, as static dynamic imports so every mode (dev,
+        // embedded build, CLI build) code-splits them through the module graph —
+        // shared Svelte runtime, component CSS handled by Vite's import helper.
+        const pageImports = Array.from(docEntries.values())
+            .filter((e) => e.kind === 'page')
+            .map((e) => `\t${JSON.stringify(encodeEntityId(e.filePath, e.entitySlug))}: () => import(${JSON.stringify(pageVirtualId(e.filePath, e.entitySlug))}),`)
+            .join('\n');
+        return `export const docs = ${JSON.stringify(data)};\nexport const cssNames = ${JSON.stringify(cssNames)};\nexport const pageModules = {\n${pageImports}\n};\nexport default docs;`;
     }
     // ─── HMR helpers ───
     function invalidateVirtualModule(docFilePath) {
@@ -415,7 +460,7 @@ export function sdocsPlugin(userConfig) {
         if (mod) {
             server.moduleGraph.invalidateModule(mod);
         }
-        // Also invalidate iframe virtual modules for the changed doc file
+        // Also invalidate iframe and page virtual modules for the changed doc file
         if (docFilePath) {
             for (const entry of entriesOf(docFilePath)) {
                 for (const snippet of allSnippets(entry)) {
@@ -425,6 +470,12 @@ export function sdocsPlugin(userConfig) {
                         server.moduleGraph.invalidateModule(iframeMod);
                     }
                 }
+                if (entry.kind === 'page') {
+                    const pageMod = server.moduleGraph.getModuleById('\0' + pageVirtualId(docFilePath, entry.entitySlug));
+                    if (pageMod) {
+                        server.moduleGraph.invalidateModule(pageMod);
+                    }
+                }
             }
         }
         server.ws.send({ type: 'full-reload' });

package/package.json

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