sdocs 0.0.56 → 0.0.58

package/dist/language/parser.js

@@ -75,6 +75,8 @@ const ENTITY_ATTR_RULES = {
     PAGE: {
         title: { required: true, kind: 'string', hint: 'title="Group / Name"' },
         ...SIZING_ATTR_RULES,
+        // On PAGE, contentX aligns the content column (with its toc), not a stage.
+        contentX: { required: false, kind: 'string', hint: 'contentX="center"' },
         toc: { required: false, kind: 'string', hint: 'toc="false"' },
     },
     LAYOUT: {
@@ -234,6 +236,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 +275,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 +291,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 +342,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 +358,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/config.js

@@ -7,6 +7,7 @@ const DEFAULTS = {
     port: 3000,
     open: false,
     css: null,
+    static: null,
     logo: 'sdocs',
     icon: 'sdocs',
     sidebar: {
@@ -14,7 +15,7 @@ const DEFAULTS = {
         open: [],
     },
     content: {
-        page: { maxWidth: '1200px', padding: '32px', toc: true },
+        page: { maxWidth: '1200px', padding: '32px', toc: true, contentX: 'left' },
         docs: {
             maxWidth: '1200px',
             padding: '16px',
@@ -69,6 +70,8 @@ export function resolveAndFinalize(userConfig, root) {
     const resolved = resolveConfig(userConfig);
     resolved.include = resolveIncludePatterns(resolved.include, root);
     resolved.css = resolveCssPaths(resolved.css, root);
+    if (resolved.static)
+        resolved.static = resolve(root, resolved.static);
     return resolved;
 }
 /** Import a config file (.js/.mjs; .ts only on Node with native type stripping) */
@@ -89,6 +92,7 @@ export function resolveConfig(userConfig) {
         port: userConfig.port ?? DEFAULTS.port,
         open: userConfig.open ?? DEFAULTS.open,
         css: userConfig.css ?? DEFAULTS.css,
+        static: userConfig.static ?? DEFAULTS.static,
         logo: userConfig.logo ?? DEFAULTS.logo,
         icon: userConfig.icon ?? DEFAULTS.icon,
         sidebar: {

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/page-markdown.d.ts

@@ -11,6 +11,9 @@ import type { TocHeading } from '../types.js';
 export interface RenderedPage {
     html: string;
     toc: TocHeading[];
+    /** Text of the body's first `#` heading, when present — it takes over as
+     * the page's displayed title. */
+    bodyTitle?: string;
 }
 /**
  * Render a [PAGE] body: Svelte islands (see segmentPageBody) pass through

package/dist/server/page-markdown.js

@@ -97,26 +97,56 @@ function plainText(tokens) {
 export async function renderPageMarkdown(source) {
     const toc = [];
     const usedIds = new Set();
+    const state = { toc, usedIds, bodyTitle: undefined };
     const parts = [];
     for (const segment of segmentPageBody(source)) {
         if (segment.kind === 'island') {
             parts.push(segment.lines.join('\n'));
         }
         else {
-            parts.push(await renderProse(segment.lines.join('\n'), toc, usedIds));
+            parts.push(await renderProse(segment.lines.join('\n'), state));
         }
     }
-    return { html: parts.join('\n'), toc };
+    return { html: parts.join('\n'), toc, bodyTitle: state.bodyTitle };
 }
-async function renderProse(source, toc, usedIds) {
+/** GitHub-style alert kinds recognized on a blockquote's first line. */
+const ALERT_KINDS = ['NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION'];
+const ALERT_RE = new RegExp(`^\\[!(${ALERT_KINDS.join('|')})\\][ \\t]*(?:\\n|$)`);
+async function renderProse(source, state) {
+    const { toc, usedIds } = state;
     const headingIds = new WeakMap();
     const fenceHtml = new WeakMap();
+    const alertKinds = new WeakMap();
     const marked = new Marked({ gfm: true });
     const tokens = marked.lexer(source);
+    /** Detect a GitHub-style alert marker on a blockquote's first line and
+     * strip it from the tokens; the renderer wraps the rest as a callout. */
+    const detectAlert = (token) => {
+        if (!('tokens' in token) || !token.tokens)
+            return;
+        const para = token.tokens[0];
+        if (para?.type !== 'paragraph' || !para.tokens)
+            return;
+        const first = para.tokens[0];
+        if (first?.type !== 'text')
+            return;
+        const m = ALERT_RE.exec(first.text ?? '');
+        if (!m)
+            return;
+        alertKinds.set(token, m[1]);
+        first.text = first.text.slice(m[0].length);
+        if (first.text === '')
+            para.tokens.shift();
+        if (para.tokens.length === 0)
+            token.tokens.shift();
+    };
     const walk = (list) => {
         for (const token of list) {
             if (token.type === 'heading') {
                 const text = plainText(token.tokens ?? []);
+                if (token.depth === 1 && state.bodyTitle === undefined) {
+                    state.bodyTitle = text;
+                }
                 const baseId = slugify(text);
                 let id = baseId;
                 for (let n = 2; usedIds.has(id); n++)
@@ -127,6 +157,8 @@ async function renderProse(source, toc, usedIds) {
                     toc.push({ text, level: token.depth, id });
                 }
             }
+            if (token.type === 'blockquote')
+                detectAlert(token);
             if ('tokens' in token && token.tokens)
                 walk(token.tokens);
             if ('items' in token && token.items)
@@ -155,6 +187,31 @@ async function renderProse(source, toc, usedIds) {
                     ? `<h${token.depth} id="${id}">${html}</h${token.depth}>\n`
                     : `<h${token.depth}>${html}</h${token.depth}>\n`;
             },
+            // GitHub-style alerts: `> [!NOTE]` blockquotes become callouts.
+            blockquote(token) {
+                const body = this.parser.parse(token.tokens ?? []);
+                const kind = alertKinds.get(token);
+                if (!kind)
+                    return `<blockquote>\n${body}</blockquote>\n`;
+                const label = kind.charAt(0) + kind.slice(1).toLowerCase();
+                return `<div class="sdocs-alert sdocs-alert-${kind.toLowerCase()}"><p class="sdocs-alert-label">${label}</p>\n${body}</div>\n`;
+            },
+            // External links open away from the docs app; hrefs stay inert.
+            link(token) {
+                const inner = this.parser.parseInline(token.tokens ?? []);
+                const href = escapeBraces(escapeHtml(token.href ?? ''));
+                const title = token.title ? ` title="${escapeBraces(escapeHtml(token.title))}"` : '';
+                const external = /^https?:\/\//i.test(token.href ?? '');
+                const attrs = external ? ' target="_blank" rel="noopener noreferrer"' : '';
+                return `<a href="${href}"${title}${attrs}>${inner}</a>`;
+            },
+            // Self-closing and brace-escaped so images are always Svelte-safe.
+            image(token) {
+                const src = escapeBraces(escapeHtml(token.href ?? ''));
+                const alt = escapeBraces(escapeHtml(token.text ?? ''));
+                const title = token.title ? ` title="${escapeBraces(escapeHtml(token.title))}"` : '';
+                return `<img src="${src}" alt="${alt}"${title} loading="lazy" />`;
+            },
             code(token) {
                 return (fenceHtml.get(token) ??
                     `<pre><code>${escapeBraces(escapeHtml(token.text))}</code></pre>\n`);

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`;