svelte-docsmith 0.14.0 → 0.16.0

package/dist/buildtime/props/typescript.js

@@ -0,0 +1,345 @@
+/**
+ * The type half of props extraction: the TypeScript checker reads a
+ * component's props type the way svelte-check does, so a prop typed with an
+ * imported alias shows its resolved union rather than the alias name. See
+ * docs/adr/0006-own-extractor-on-typescript-checker.md.
+ *
+ * Each `.svelte` file is served to TypeScript as a virtual `X.svelte.ts`
+ * holding its svelte2tsx output. One language service lives per Vite root and
+ * is reused across props imports, so unchanged files aren't re-parsed.
+ *
+ * `typescript` and `svelte2tsx` are optional peer dependencies, loaded only when
+ * a page imports `?props`.
+ */
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+export const MISSING_PEERS = 'Generated props tables need TypeScript. Install the optional peer ' +
+    'dependencies with: npm i -D typescript svelte2tsx';
+let loaded;
+/** Load the optional peers once per process; `undefined` when not installed. */
+export function loadPeers() {
+    loaded ??= (async () => {
+        try {
+            const [tsModule, s2t] = await Promise.all([import('typescript'), import('svelte2tsx')]);
+            const ts = (tsModule.default ?? tsModule);
+            const dir = path.dirname(createRequire(import.meta.url).resolve('svelte2tsx'));
+            const shims = ['svelte-shims-v4.d.ts', 'svelte-jsx-v4.d.ts'].map((f) => path.join(dir, f));
+            return { ts, svelte2tsx: s2t.svelte2tsx, shims };
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    return loaded;
+}
+/** A file's modification time, or `-1` when it can't be read. */
+export function mtimeOf(file) {
+    try {
+        return fs.statSync(file).mtimeMs;
+    }
+    catch {
+        return -1;
+    }
+}
+/** Whether a path lies inside a `node_modules` directory, on any platform. */
+export function inNodeModules(file) {
+    return /[\\/]node_modules[\\/]/.test(file);
+}
+const formatFlags = (ts) => ts.TypeFormatFlags.NoTruncation |
+    ts.TypeFormatFlags.UseSingleQuotesForStringLiteralType |
+    ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope;
+export function createPropsTypeChecker({ ts, svelte2tsx, shims }, options) {
+    const compilerOptions = readCompilerOptions(ts, options.root, options.tsconfig);
+    const roots = new Set();
+    const generated = new Map();
+    const mtime = mtimeOf;
+    // `X.svelte.ts` stands for `X.svelte` unless a real `X.svelte.ts` (a runes
+    // module) exists.
+    const isVirtual = (file) => file.endsWith('.svelte.ts') && !ts.sys.fileExists(file) && ts.sys.fileExists(file.slice(0, -3));
+    /** The file on disk a program file stands for. */
+    const onDisk = (file) => (isVirtual(file) ? file.slice(0, -3) : file);
+    const readVirtual = (file) => {
+        const svelteFile = file.slice(0, -3);
+        const time = mtime(svelteFile);
+        const cached = generated.get(svelteFile);
+        if (cached && cached.mtime === time)
+            return cached.code;
+        const { code } = svelte2tsx(fs.readFileSync(svelteFile, 'utf-8'), {
+            filename: svelteFile,
+            isTsFile: true,
+            mode: 'ts',
+            version: options.svelteVersion
+        });
+        generated.set(svelteFile, { mtime: time, code });
+        return code;
+    };
+    const fileExists = (file) => isVirtual(file) || ts.sys.fileExists(file);
+    const readFile = (file) => (isVirtual(file) ? readVirtual(file) : ts.sys.readFile(file));
+    const resolutionHost = {
+        fileExists,
+        readFile,
+        directoryExists: ts.sys.directoryExists,
+        realpath: ts.sys.realpath,
+        getCurrentDirectory: () => options.root,
+        getDirectories: ts.sys.getDirectories
+    };
+    const host = {
+        getCompilationSettings: () => compilerOptions,
+        getScriptFileNames: () => [...shims, ...roots],
+        getScriptVersion: (file) => String(mtime(onDisk(file))),
+        getScriptSnapshot: (file) => {
+            const text = readFile(file);
+            return text === undefined ? undefined : ts.ScriptSnapshot.fromString(text);
+        },
+        getCurrentDirectory: () => options.root,
+        getDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),
+        fileExists,
+        readFile,
+        directoryExists: ts.sys.directoryExists,
+        getDirectories: ts.sys.getDirectories,
+        realpath: ts.sys.realpath,
+        resolveModuleNameLiterals(literals, containingFile, redirected, opts, containingSourceFile) {
+            return literals.map((literal) => resolveModule(literal.text, containingFile, opts, redirected, {
+                mode: ts.getModeForUsageLocation(containingSourceFile, literal, opts)
+            }));
+        }
+    };
+    // A `.svelte` specifier resolves like its `.svelte.js` twin, which every
+    // resolution mode maps onto the virtual `.svelte.ts`. That keeps relative
+    // imports, package `imports` (`#lib/…`) and tsconfig `paths` working.
+    function resolveModule(name, containingFile, opts = compilerOptions, redirected, { mode } = {}) {
+        const resolve = (spec) => ts.resolveModuleName(spec, containingFile, opts, resolutionHost, undefined, redirected, mode);
+        const result = resolve(name);
+        if (result.resolvedModule || !name.endsWith('.svelte'))
+            return result;
+        return resolve(name + '.js');
+    }
+    const service = ts.createLanguageService(host, ts.createDocumentRegistry());
+    // The project files a component pulls in (its type imports included), so
+    // editing a shared `types.ts` re-extracts the props that use it.
+    const dependencies = (program, entry) => {
+        const seen = new Set([entry.fileName]);
+        const queue = [entry.fileName];
+        for (let file = queue.shift(); file; file = queue.shift()) {
+            const text = program.getSourceFile(file)?.text ?? '';
+            for (const { fileName } of ts.preProcessFile(text, true, true).importedFiles) {
+                const target = resolveModule(fileName, file).resolvedModule?.resolvedFileName;
+                if (!target || inNodeModules(target) || seen.has(target))
+                    continue;
+                seen.add(target);
+                queue.push(target);
+            }
+        }
+        return [...seen].map(onDisk);
+    };
+    return {
+        read(files) {
+            for (const file of files)
+                roots.add(file + '.ts');
+            const program = service.getProgram();
+            return files.map((file) => {
+                try {
+                    const source = program?.getSourceFile(file + '.ts');
+                    if (!program || !source)
+                        return undefined;
+                    const typed = readProps(ts, program, source);
+                    return typed && { ...typed, files: dependencies(program, source) };
+                }
+                catch (error) {
+                    return error instanceof Error ? error : new Error(String(error));
+                }
+            });
+        }
+    };
+}
+function readCompilerOptions(ts, root, tsconfig) {
+    const configFile = tsconfig
+        ? path.resolve(root, tsconfig)
+        : ts.findConfigFile(root, ts.sys.fileExists, 'tsconfig.json');
+    let base = {
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        strict: true
+    };
+    if (configFile && ts.sys.fileExists(configFile)) {
+        const parsed = ts.getParsedCommandLineOfConfigFile(configFile, {}, {
+            ...ts.sys,
+            onUnRecoverableConfigFileDiagnostic: () => { }
+        });
+        if (parsed)
+            base = parsed.options;
+    }
+    return {
+        ...base,
+        allowJs: true,
+        skipLibCheck: true,
+        noEmit: true,
+        declaration: false,
+        composite: false,
+        incremental: false
+    };
+}
+function readProps(ts, program, source) {
+    const typeNode = findPropsTypeNode(ts, source);
+    if (!typeNode)
+        return undefined;
+    const checker = program.getTypeChecker();
+    const flags = formatFlags(ts);
+    const propsType = checker.getTypeFromTypeNode(typeNode);
+    const isExternal = (sf) => program.isSourceFileFromExternalLibrary(sf) ||
+        program.isSourceFileDefaultLibrary(sf) ||
+        inNodeModules(sf.fileName);
+    const declaredOutside = (symbol) => {
+        const declarations = symbol.getDeclarations() ?? [];
+        return declarations.length > 0 && declarations.every((d) => isExternal(d.getSourceFile()));
+    };
+    // A prop typed with an alias from a library (`ClassValue`) keeps its name:
+    // expanding it would print the library's internals. Project aliases fall
+    // through to `printPropType`, which expands them.
+    const libraryAlias = (symbol) => {
+        const declaration = symbol.valueDeclaration;
+        if (!declaration || !ts.isPropertySignature(declaration) || !declaration.type)
+            return;
+        const declared = checker.getTypeFromTypeNode(declaration.type);
+        const alias = declared.aliasSymbol?.getDeclarations() ?? [];
+        if (alias.length === 0 || !alias.every((d) => isExternal(d.getSourceFile())))
+            return;
+        return checker.typeToString(declared, typeNode, flags);
+    };
+    const props = [];
+    let anyInherited = false;
+    for (const symbol of checker.getPropertiesOfType(propsType)) {
+        if (declaredOutside(symbol)) {
+            anyInherited = true;
+            continue;
+        }
+        const optional = (symbol.flags & ts.SymbolFlags.Optional) !== 0;
+        const tags = symbol.getJsDocTags(checker);
+        const tag = (name) => {
+            const found = tags.find((t) => t.name === name);
+            return found ? ts.displayPartsToString(found.text ?? []).trim() : undefined;
+        };
+        const description = ts.displayPartsToString(symbol.getDocumentationComment(checker)).trim();
+        props.push({
+            name: symbol.name,
+            type: libraryAlias(symbol) ??
+                printPropType(ts, checker, checker.getTypeOfSymbol(symbol), optional, typeNode, flags),
+            optional,
+            description: description || undefined,
+            deprecated: tag('deprecated'),
+            defaultTag: tag('default'),
+            internal: tag('internal') !== undefined
+        });
+    }
+    const inherited = anyInherited
+        ? inheritedGroups(ts, program, checker, propsType, declaredOutside, typeNode, flags)
+        : [];
+    return { props, inherited, files: [] };
+}
+/** The type annotation on the `$props()` declaration in the svelte2tsx output. */
+function findPropsTypeNode(ts, source) {
+    let found;
+    const visit = (node) => {
+        if (found)
+            return;
+        if (ts.isVariableDeclaration(node) &&
+            node.initializer &&
+            ts.isCallExpression(node.initializer) &&
+            ts.isIdentifier(node.initializer.expression) &&
+            node.initializer.expression.text === '$props') {
+            found = node.type;
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return found;
+}
+/** `Snippet<[]>` is how the checker spells a bare `Snippet`. */
+const bareSnippet = (type) => type.replace(/\bSnippet<\[\]>/g, 'Snippet');
+/**
+ * A union prints member by member: an alias of literals (`BadgeVariant`)
+ * expands to its values, and the `undefined` an optional prop picks up is
+ * dropped. Any other type prints as written (`Snippet`, `Item[]`, `T`).
+ */
+function printPropType(ts, checker, type, optional, enclosing, flags) {
+    if (!type.isUnion())
+        return bareSnippet(checker.typeToString(type, enclosing, flags));
+    let members = type.types.filter((t) => !(optional && t.flags & ts.TypeFlags.Undefined));
+    const booleans = members.filter((t) => t.flags & ts.TypeFlags.BooleanLiteral);
+    const parts = [];
+    let wroteBoolean = false;
+    if (booleans.length === 2) {
+        members = members.filter((t) => !booleans.includes(t));
+        wroteBoolean = true;
+    }
+    for (const member of members)
+        parts.push(bareSnippet(checker.typeToString(member, enclosing, flags)));
+    if (wroteBoolean)
+        parts.push('boolean');
+    if (parts.length === 1)
+        return parts[0];
+    return parts.map((p) => (p.includes('=>') ? `(${p})` : p)).join(' | ');
+}
+/**
+ * Name what the external props came from: each part of the props intersection
+ * (or base of the props interface) whose props are all declared outside the
+ * project. An element's attributes (`HTMLAnchorAttributes`) are named by tag.
+ */
+function inheritedGroups(ts, program, checker, propsType, declaredOutside, enclosing, flags) {
+    const parts = [];
+    const collect = (type) => {
+        if (type.isIntersection()) {
+            type.types.forEach(collect);
+            return;
+        }
+        const props = checker.getPropertiesOfType(type);
+        if (props.length > 0 && props.every(declaredOutside)) {
+            parts.push(type);
+            return;
+        }
+        const target = type.target ?? type;
+        if (target.isClassOrInterface()) {
+            for (const base of checker.getBaseTypes(target))
+                collect(base);
+        }
+    };
+    collect(propsType);
+    const tags = elementTags(program, checker);
+    const groups = parts.map((type) => {
+        const tag = tags.get(type);
+        return tag
+            ? { kind: 'element', label: tag }
+            : { kind: 'type', label: checker.typeToString(type, enclosing, flags) };
+    });
+    return groups.length > 0 ? groups : [{ kind: 'type', label: 'more inherited attributes' }];
+}
+/**
+ * Attribute types that belong to exactly one tag in Svelte's
+ * `SvelteHTMLElements` map (`HTMLAnchorAttributes` → `a`). Shared types like
+ * `HTMLAttributes<HTMLElement>` map to many tags, so they keep their name.
+ */
+function elementTags(program, checker) {
+    const tags = new Map();
+    const elements = program
+        .getSourceFiles()
+        .find((sf) => /[\\/]svelte[\\/]elements\.d\.ts$/.test(sf.fileName));
+    const moduleSymbol = elements && checker.getSymbolAtLocation(elements);
+    const map = moduleSymbol &&
+        checker.getExportsOfModule(moduleSymbol).find((s) => s.name === 'SvelteHTMLElements');
+    if (!map)
+        return tags;
+    const shared = new Set();
+    for (const entry of checker.getPropertiesOfType(checker.getDeclaredTypeOfSymbol(map))) {
+        const type = checker.getTypeOfSymbol(entry);
+        if (tags.has(type))
+            shared.add(type);
+        else
+            tags.set(type, entry.name);
+    }
+    for (const type of shared)
+        tags.delete(type);
+    return tags;
+}

package/dist/buildtime/vite/agent-markdown.d.ts

@@ -0,0 +1,43 @@
+import { type ExtractedProps } from '../../core/extracted-props.js';
+import type { SourcePage } from './pages.js';
+/** Which build-time transform a page import goes through. */
+export type DocImportKind = 'source' | 'props';
+/** One `*.svelte?source` or `*.svelte?props` import in a page's `<script>`. */
+export type DocImport = {
+    kind: DocImportKind;
+    /** The specifier as written, query included, for messages. */
+    specifier: string;
+    /** The component file it resolves to, or `undefined` when it did not resolve. */
+    file: string | undefined;
+};
+/**
+ * Resolve a specifier (query stripped) from a page, the way Vite resolves the
+ * page's own imports: the app's aliases (`$lib`, `#lib`) included. Returns the
+ * resolved file, or `undefined` when nothing resolves it.
+ */
+export type ResolveImport = (specifier: string, importer: string) => Promise<string | undefined>;
+/** What building agent markdown needs from the plugin. */
+export type AgentMarkdownHost = {
+    resolve: ResolveImport;
+    /** Record a file the agent markdown was read from, so editing it rebuilds the index. */
+    watch(file: string): void;
+    warn(message: string): void;
+    /**
+     * A component's props as the `?props` transform extracts them, with
+     * descriptions as markdown. The host watches the files they were read from
+     * and passes on extraction warnings.
+     */
+    props(file: string): Promise<ExtractedProps>;
+};
+/**
+ * A page's `?source` and `?props` imports, keyed by the local name each binds,
+ * with every specifier resolved from the page. Imports inside fenced code
+ * samples are not the page's, and are skipped.
+ */
+export declare function docImports(page: Pick<SourcePage, 'file' | 'source'>, resolve: ResolveImport): Promise<Map<string, DocImport>>;
+/**
+ * Build the agent markdown rewrite for one page: a function from the page's
+ * markdown, setup blocks stripped, to its agent markdown. `undefined` when the page imports nothing
+ * agent markdown expands, so most pages cost one scan of their script.
+ */
+export declare function agentMarkdownFor(page: SourcePage, host: AgentMarkdownHost): Promise<((content: string) => string) | undefined>;

package/dist/buildtime/vite/agent-markdown.js

@@ -0,0 +1,204 @@
+/**
+ * Agent markdown: a page's markdown as an agent reads it (llms-full.txt, the
+ * `.md` twins, the MCP server). The page as written keeps `<LiveExample
+ * source={…}>` and `<PropsTable of={…}>` as bare tags and their imports are
+ * stripped with the `<script>` block, so an agent would never see the example
+ * code or the component's props. Here each `LiveExample` whose source is a
+ * `?source` import becomes a fenced `svelte` block of the example file's raw
+ * source, and each `PropsTable` whose `of` is a props import becomes a heading
+ * and a markdown table of the same rows the page renders.
+ *
+ * Unlike `./collect.js` this reads the filesystem and resolves imports, so it
+ * runs in the plugin, which hands it Vite's resolver and the props extractor.
+ */
+import fs from 'node:fs';
+import { propsCaption } from '../../core/extracted-props.js';
+import { outsideCodeFenceRuns, scriptBlocks } from '../markdown-source.js';
+import { relativeToCwd } from '../paths.js';
+/** A default import of a `.svelte` file through `?source` or `?props`. */
+const DOC_IMPORT = /\bimport\s+([A-Za-z_$][\w$]*)\s+from\s*(['"])([^'"\n]+?\.svelte)\?(source|props)\2/g;
+/**
+ * A page's `?source` and `?props` imports, keyed by the local name each binds,
+ * with every specifier resolved from the page. Imports inside fenced code
+ * samples are not the page's, and are skipped.
+ */
+export async function docImports(page, resolve) {
+    const imports = new Map();
+    for (const block of scriptBlocks(page.source)) {
+        for (const [, local, , base, kind] of block.matchAll(DOC_IMPORT)) {
+            const file = await resolve(base, page.file);
+            imports.set(local, { kind: kind, specifier: `${base}?${kind}`, file });
+        }
+    }
+    return imports;
+}
+/**
+ * A `<LiveExample …>…</LiveExample>` (or self-closing) tag starting a line.
+ * Group 1 is its indentation, group 2 its attributes; an attribute value in
+ * braces may contain `>`.
+ */
+const LIVE_EXAMPLE = /^([ \t]*)<LiveExample\b((?:[^>{}]|\{[^{}]*\})*?)(?:\/>|>[\s\S]*?<\/LiveExample\s*>)/gm;
+/** `source={name}`, or the `{source}` shorthand. */
+const SOURCE_ATTRIBUTE = /(?:\bsource\s*=\s*\{\s*([A-Za-z_$][\w$]*)\s*\}|\{\s*(source)\s*\})/;
+/** A backtick fence one longer than the longest backtick run in `text`, and at least `min`. */
+function fenceFor(text, min) {
+    const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map(([run]) => run.length));
+    return '`'.repeat(Math.max(min, longest + 1));
+}
+/** `text` with `indent` before each non-empty line. */
+function indented(text, indent) {
+    return text
+        .split('\n')
+        .map((line) => (line ? indent + line : line))
+        .join('\n');
+}
+/** A fenced block of `code`, fenced longer than any backtick run inside it. */
+function fenced(code, lang, indent) {
+    const fence = fenceFor(code, 3);
+    return indented([fence + lang, code, fence].join('\n'), indent);
+}
+/**
+ * Build the agent markdown rewrite for one page: a function from the page's
+ * markdown, setup blocks stripped, to its agent markdown. `undefined` when the page imports nothing
+ * agent markdown expands, so most pages cost one scan of their script.
+ */
+export async function agentMarkdownFor(page, host) {
+    const imports = await docImports(page, host.resolve);
+    if (imports.size === 0)
+        return undefined;
+    // Read up front, so the rewrite itself is synchronous. Props extractions all
+    // start together, so the extractor batches them into one TypeScript update.
+    const sources = new Map();
+    const tables = new Map();
+    await Promise.all([...imports].map(async ([local, entry]) => {
+        // Watched even when it can't be read, so creating or fixing it rebuilds.
+        if (entry.file !== undefined)
+            host.watch(entry.file);
+        if (entry.kind === 'source') {
+            sources.set(local, entry.file === undefined ? undefined : readExample(entry.file));
+        }
+        else {
+            tables.set(local, entry.file === undefined ? undefined : await host.props(entry.file));
+        }
+    }));
+    const keepTag = (tag, local, attribute) => {
+        host.warn(`${relativeToCwd(page.file)}: could not read \`${imports.get(local)?.specifier}\` ` +
+            `for <${tag} ${attribute}={${local}}>, so agent markdown keeps the tag.`);
+    };
+    return (content) => {
+        // The level of the heading a table sits under, carried across code fences.
+        let level = 1;
+        return outsideCodeFenceRuns(content, (prose) => {
+            const levelAt = (offset) => lastHeadingLevel(prose.slice(0, offset)) ?? level;
+            const withTables = prose.replace(PROPS_TABLE, (tag, indent, attributes, offset) => {
+                const match = OF_ATTRIBUTE.exec(attributes);
+                const local = match?.[1] ?? match?.[2];
+                if (local === undefined || !tables.has(local))
+                    return tag;
+                const props = tables.get(local);
+                if (props === undefined) {
+                    keepTag('PropsTable', local, 'of');
+                    return tag;
+                }
+                const title = TITLE_ATTRIBUTE.exec(attributes);
+                const caption = title ? title.slice(1).find((value) => value !== undefined) : undefined;
+                return propsTable(props, caption, Math.min(6, levelAt(offset) + 1), indent);
+            });
+            level = levelAt(prose.length);
+            return withTables.replace(LIVE_EXAMPLE, (tag, indent, attributes) => {
+                const match = SOURCE_ATTRIBUTE.exec(attributes);
+                const local = match?.[1] ?? match?.[2];
+                if (local === undefined || !sources.has(local))
+                    return tag;
+                const code = sources.get(local);
+                if (code === undefined) {
+                    keepTag('LiveExample', local, 'source');
+                    return tag;
+                }
+                return fenced(code, 'svelte', indent);
+            });
+        });
+    };
+}
+/**
+ * A `<PropsTable …/>` or `<PropsTable …>…</PropsTable>` tag starting a line,
+ * grouped like {@link LIVE_EXAMPLE}.
+ */
+const PROPS_TABLE = /^([ \t]*)<PropsTable\b((?:[^>{}]|\{[^{}]*\})*?)(?:\/>|>[\s\S]*?<\/PropsTable\s*>)/gm;
+/** `of={name}`, or the `{of}` shorthand. */
+const OF_ATTRIBUTE = /(?:(?:^|\s)of\s*=\s*\{\s*([A-Za-z_$][\w$]*)\s*\}|\{\s*(of)\s*\})/;
+/** A `title` given as a string literal, quoted or in braces. */
+const TITLE_ATTRIBUTE = /(?:^|\s)title\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*(?:"([^"]*)"|'([^']*)')\s*\})/;
+/** An ATX heading's marker. */
+const HEADING = /^ {0,3}(#{1,6})(?:[ \t]|$)/gm;
+/** The level of the last heading in `prose`, if it has one. */
+function lastHeadingLevel(prose) {
+    return [...prose.matchAll(HEADING)].at(-1)?.[1].length;
+}
+/**
+ * A generated props table as agent markdown: the caption as a heading, then a
+ * `Prop | Type | Default | Description` table with the rows the page renders,
+ * then the inherited attributes summary.
+ */
+function propsTable(props, title, level, indent) {
+    const blocks = [`${'#'.repeat(level)} ${code(title ?? propsCaption(props))}`];
+    if (props.props.length) {
+        blocks.push([
+            '| Prop | Type | Default | Description |',
+            '| --- | --- | --- | --- |',
+            ...props.props.map((prop) => `| ${propCells(prop).join(' | ')} |`)
+        ].join('\n'));
+    }
+    for (const group of props.inherited) {
+        blocks.push(group.kind === 'element'
+            ? `Also accepts every ${code(`<${group.label}>`)} attribute.`
+            : `Also accepts every prop of ${code(group.label)}.`);
+    }
+    if (props.props.length === 0 && props.inherited.length === 0)
+        blocks.push('No props.');
+    return indented(blocks.join('\n\n'), indent);
+}
+/** One row's cells, marked as the rendered row is and escaped for a table. */
+function propCells(prop) {
+    let name = code(prop.required ? prop.name : `${prop.name}?`);
+    if (prop.deprecated !== undefined)
+        name = `~~${name}~~`;
+    const marks = [
+        prop.bindable && '*(bindable)*',
+        prop.deprecated !== undefined && '*(deprecated)*'
+    ];
+    const description = [prop.deprecated && `Deprecated: ${prop.deprecated}`, prop.description]
+        .filter(Boolean)
+        .map((text) => inline(text))
+        .join('<br>');
+    return [
+        [name, ...marks.filter(Boolean)].join(' '),
+        prop.type === undefined ? '' : code(prop.type),
+        prop.default === undefined ? '' : code(prop.default),
+        description
+    ].map((cell) => cell.replaceAll('|', '\\|'));
+}
+/** `text` as a code span on one line, fenced longer than any backtick run in it. */
+function code(text) {
+    const flat = text.replace(/\s*\n\s*/g, ' ');
+    const fence = fenceFor(flat, 1);
+    const pad = flat.startsWith('`') || flat.endsWith('`') ? ' ' : '';
+    return fence + pad + flat + pad + fence;
+}
+/** Markdown on one line: paragraphs joined with `<br><br>`, soft breaks as spaces. */
+function inline(markdown) {
+    return markdown
+        .trim()
+        .split(/\n[ \t]*\n\s*/)
+        .map((paragraph) => paragraph.replace(/\s*\n\s*/g, ' '))
+        .join('<br><br>');
+}
+/** An example file's raw source, as the `?source` transform reads it. */
+function readExample(file) {
+    try {
+        return fs.readFileSync(file, 'utf-8').trimEnd();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/buildtime/vite/collect.d.ts

@@ -29,5 +29,8 @@ export declare function searchIndex(pages: SourcePage[], options: IndexOptions):
  * The LLM index: title, section, description, and the full markdown content.
  * Served as the `svelte-docsmith/llms` virtual module and consumed server-side
  * by `llms.txt` / `llms-full.txt` routes, so it never ships to the client.
+ *
+ * `rewrite` turns a page's markdown into agent markdown (see
+ * `./agent-markdown.js`); without it, the content is the page as written.
  */
-export declare function llmsIndex(pages: SourcePage[], options: IndexOptions): LlmsDoc[];
+export declare function llmsIndex(pages: SourcePage[], options: IndexOptions, rewrite?: (content: string, page: SourcePage) => string): LlmsDoc[];