sdocs 0.0.40 → 0.0.42

package/dist/server/app-gen.js

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

package/dist/server/discovery.d.ts

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

package/dist/server/discovery.js

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

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

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

package/dist/server/doc-model.js

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

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

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

package/dist/server/page-markdown.js

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

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

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

package/dist/server/snippet-compiler.js

@@ -15,13 +15,25 @@ let docPathRoot = process.cwd();
 export function setDocPathRoot(root) {
     docPathRoot = root;
 }
-/** Encode a doc file path for use in URLs and emitted file names */
-export function encodeDocPath(filePath) {
-    return base64urlEncode(relative(docPathRoot, filePath).split(sep).join('/'));
+/** Encode a doc entity (file + entity slug) for URLs and emitted file names.
+ * The slug rides inside the token as a '#' fragment so every URL shape keeps
+ * exactly one token path segment. */
+export function encodeEntityId(filePath, entitySlug) {
+    return base64urlEncode(relative(docPathRoot, filePath).split(sep).join('/') + '#' + entitySlug);
 }
-/** Decode an encoded doc path back to an absolute path */
-function decodeDocPath(encoded) {
-    return resolve(docPathRoot, base64urlDecode(encoded));
+/** Decode an encoded entity id back to an absolute path + entity slug */
+function decodeEntityId(encoded) {
+    const decoded = base64urlDecode(encoded);
+    const hash = decoded.lastIndexOf('#');
+    const relPath = hash === -1 ? decoded : decoded.slice(0, hash);
+    return {
+        docFilePath: resolve(docPathRoot, relPath),
+        entitySlug: hash === -1 ? '' : decoded.slice(hash + 1),
+    };
+}
+/** The docEntries key for one entity of one file */
+export function entityKey(filePath, entitySlug) {
+    return `${filePath}#${entitySlug}`;
 }
 /** Resolve relative imports to absolute paths for use in virtual components */
 export function resolveImportsToAbsolute(imports, docFilePath) {
@@ -206,48 +218,39 @@ export function generateStaticPreviewHtml(scriptSrc, cssLinks) {
     return previewHtmlShell(links, `<script type="module" src="${scriptSrc}"></script>`);
 }
 /** Build the virtual module ID for an iframe wrapper component */
-export function iframeVirtualId(docFilePath, snippetName) {
-    return `/@sdocs/iframe/${encodeDocPath(docFilePath)}/${snippetName}.svelte`;
+export function iframeVirtualId(docFilePath, entitySlug, snippetSlug) {
+    return `/@sdocs/iframe/${encodeEntityId(docFilePath, entitySlug)}/${snippetSlug}.svelte`;
 }
 /** Build the preview URL for an iframe HTML page (dev mode) */
-export function previewUrl(docFilePath, snippetName) {
-    return `/@sdocs/preview/${encodeDocPath(docFilePath)}/${snippetName}`;
+export function previewUrl(docFilePath, entitySlug, snippetSlug) {
+    return `/@sdocs/preview/${encodeEntityId(docFilePath, entitySlug)}/${snippetSlug}`;
 }
 /** Build the preview URL for static build output */
-export function buildPreviewUrl(docFilePath, snippetName) {
-    return `/previews/${encodeDocPath(docFilePath)}/${snippetName}.html`;
+export function buildPreviewUrl(docFilePath, entitySlug, snippetSlug) {
+    return `/previews/${encodeEntityId(docFilePath, entitySlug)}/${snippetSlug}.html`;
 }
 /** Virtual module ID for a preview's mount script (embedded production builds) */
-export function mountVirtualId(docFilePath, snippetName) {
-    return `/@sdocs/mount/${encodeDocPath(docFilePath)}/${snippetName}.js`;
+export function mountVirtualId(docFilePath, entitySlug, snippetSlug) {
+    return `/@sdocs/mount/${encodeEntityId(docFilePath, entitySlug)}/${snippetSlug}.js`;
 }
 /** Parse a mount virtual ID back into its parts */
 export function parseMountId(id) {
-    const match = id.match(/^\/@sdocs\/mount\/([^/]+)\/(\w+)\.js$/);
+    const match = id.match(/^\/@sdocs\/mount\/([^/]+)\/([\w-]+)\.js$/);
     if (!match)
         return null;
-    return {
-        docFilePath: decodeDocPath(match[1]),
-        snippetName: match[2],
-    };
+    return { ...decodeEntityId(match[1]), snippetSlug: match[2] };
 }
 /** Parse an iframe virtual ID back into its parts */
 export function parseIframeId(id) {
-    const match = id.match(/^\/@sdocs\/iframe\/([^/]+)\/(\w+)\.svelte$/);
+    const match = id.match(/^\/@sdocs\/iframe\/([^/]+)\/([\w-]+)\.svelte$/);
     if (!match)
         return null;
-    return {
-        docFilePath: decodeDocPath(match[1]),
-        snippetName: match[2],
-    };
+    return { ...decodeEntityId(match[1]), snippetSlug: match[2] };
 }
 /** Parse a preview URL back into its parts */
 export function parsePreviewUrl(url) {
-    const match = url.match(/^\/@sdocs\/preview\/([^/]+)\/(\w+)$/);
+    const match = url.match(/^\/@sdocs\/preview\/([^/]+)\/([\w-]+)$/);
     if (!match)
         return null;
-    return {
-        docFilePath: decodeDocPath(match[1]),
-        snippetName: match[2],
-    };
+    return { ...decodeEntityId(match[1]), snippetSlug: match[2] };
 }

package/dist/types.d.ts

@@ -33,18 +33,12 @@ export interface ResolvedSdocsConfig {
         open: string[];
     };
 }
-/** Meta extracted from a .sdoc file */
+/** Entity metadata from a [DOCS]/[PAGE]/[LAYOUT] opener */
 export interface SdocMeta {
-    /** The Svelte component being documented */
-    component?: unknown;
     /** Sidebar path (e.g. 'Demo / Button') */
     title: string;
     /** Short description */
     description?: string;
-    /** Default prop values */
-    args?: Record<string, unknown>;
-    /** Preview settings (padding, background, etc.) */
-    settings?: Record<string, unknown>;
 }
 /** A parsed prop */
 export interface ParsedProp {
@@ -82,36 +76,58 @@ export interface ComponentData {
     state: ParsedState[];
     cssProps: ParsedCssProp[];
 }
-/** An extracted snippet */
+/** A renderable snippet of an entity: a preview, an example, or the body */
 export interface ExtractedSnippet {
+    /** Display name: preview label / example title / 'Content' */
     name: string;
+    /** URL-safe id, unique within the entity */
+    slug: string;
+    role: 'preview' | 'example' | 'content';
     body: string;
     highlightedHtml?: string;
     /** Preview URL for iframe (added by virtual module) */
     previewUrl?: string;
 }
+/** One [preview] of a DOCS entity: a live showcase of one component */
+export interface PreviewEntry {
+    /** Tab label (title override or the component name) */
+    label: string;
+    /** The previewed component's identifier in the file's script */
+    componentName: string | null;
+    /** Absolute path to the previewed component */
+    componentPath: string | null;
+    /** Parsed component data (props, methods, state, CSS props) */
+    componentData: ComponentData | null;
+    /** Highlighted component source HTML */
+    highlightedSource: string | null;
+    /** Control defaults for this preview */
+    args: Record<string, unknown>;
+    snippet: ExtractedSnippet;
+}
 /** A table of contents heading (for pages) */
 export interface TocHeading {
     text: string;
     level: number;
     id: string;
 }
-/** A complete doc entry (one .sdoc file) */
+/** A complete doc entry (one entity of one .sdoc file) */
 export interface DocEntry {
-    /** Doc kind */
+    /** Doc kind: DOCS / PAGE / LAYOUT */
     kind: 'component' | 'page' | 'layout';
     /** Absolute path to the .sdoc file */
     filePath: string;
-    /** Absolute path to the documented component */
-    componentPath: string | null;
-    /** Parsed meta */
+    /** URL-safe entity id, unique within the file */
+    entitySlug: string;
+    /** Entity metadata (title drives the sidebar) */
     meta: SdocMeta;
-    /** Parsed component data (props, methods, state, CSS props) */
-    componentData: ComponentData | null;
-    /** Extracted snippets */
-    snippets: ExtractedSnippet[];
-    /** Highlighted component source HTML */
-    highlightedSource: string | null;
+    /** Live previews (component kind; empty otherwise) */
+    previews: PreviewEntry[];
+    /** Frozen examples (component kind; empty otherwise) */
+    examples: ExtractedSnippet[];
+    /** The rendered body (page/layout kind; null otherwise) */
+    content: ExtractedSnippet | null;
     /** Table of contents headings (pages only) */
     toc?: TocHeading[];
+    /** Stage padding (layouts only) */
+    padding?: string | null;
 }