import { type StageIdentityAttrs } from './preview-runtime.js';
/** Base64url encode a string (URL-safe, no padding) */
export declare function base64urlEncode(str: string): string;
/** Base64url decode */
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 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;
/**
 * Find the entry a parsed id refers to.
 *
 * Normally the key matches outright. The fallback exists for a token encoded
 * against a different root — a standalone MCP server has no dev server to ask
 * which one — and matching by path suffix beats telling a caller that a stage
 * it can see plainly doesn't exist. It has to apply everywhere an id is
 * resolved, not just at the first hop: serving the preview shell and then
 * 404-ing the module it imports produces a page that loads and shows nothing,
 * which is worse than an honest miss.
 */
export declare function lookupEntry<T>(entries: Map<string, T>, parsed: {
    docFilePath: string;
    entitySlug: string;
    relPath?: string;
}): T | undefined;
/** Resolve relative imports to absolute paths for use in virtual components */
export declare function resolveImportsToAbsolute(imports: string[], docFilePath: string): string[];
/** One relative import: its specifier and where it sits in the script. */
export interface ScannedImport {
    spec: string;
    start: number;
    end: number;
}
/**
 * The script's *relative* import specifiers, with their offsets.
 *
 * Matches against the scrubbed text (comments and string/template contents
 * blanked, offsets preserved) so an import-shaped substring inside a string
 * literal — a code sample, say — is never treated as an import; the real
 * specifier is then read back from the original at the same offsets. Bare
 * specifiers (npm packages) are skipped: only relative paths are ours to
 * resolve. Single source of truth for both rewriting and existence checks.
 */
export declare function scanRelativeImports(script: string): ScannedImport[];
export declare function resolveScriptImports(script: string, docFilePath: string): string;
/** Generate a virtual Svelte iframe wrapper component for a snippet.
 * Includes $state for reactive prop updates via postMessage, invokes
 * component methods on request, and broadcasts exported state values. */
export declare function generateIframeComponent(scriptPrelude: string, snippetBody: string, stateNames?: string[], componentName?: string, stage?: {
    maxWidth: string;
    padding: string;
    direction?: string;
    gap?: string;
    contentX?: string;
    contentY?: string;
    background?: string;
    minHeight?: string;
}, extras?: {
    /** The block's declared `args={{ … }}` literal — seeded as the initial
     * state so a component using a required prop has it on first render,
     * before the Controls' first message arrives. */
    args?: Record<string, string | number | boolean | null>;
    /** Block-level <script> content (imports already resolved), appended
     * after the wrapper plumbing so it can reference `args`. */
    blockScript?: string;
    /** CSS injected into the stage: the file-level <style> plus the block's
     * own <style>. Emitted as a real style element — the iframe already
     * isolates it to this one block. */
    styles?: string;
}): string;
/**
 * Generate the Svelte component for a [DOC] or [PAGE] body, rendered natively
 * inside the Explorer (sdocs styling — the project's css never loads here).
 * DOC prose arrives as rendered markdown with islands verbatim, and
 * `{@render __sdocsExample?.(i)}` and `{@render __sdocsGlossary?.(i)}`
 * markers render the example stages and glossaries the
 * Explorer passes in as a snippet prop; a PAGE body is plain Svelte.
 */
export declare function generatePageComponent(scriptPrelude: string, renderedBody: string, fileStyle?: string): string;
/**
 * The JS that boots a preview page: mount the wrapper + parent-frame messaging.
 *
 * The import is dynamic and guarded on purpose. A stage's `<script>` runs when
 * its module is evaluated, so anything that throws there — a `JSON.parse` on a
 * fixture, a missing export read at the top level — kills the preview page
 * before `mount` is ever reached. With a static import there is nothing to
 * catch, and the reader gets a documentation page with a silent empty frame
 * while the build reports success. Now the frame says what threw.
 */
export declare function generateMountScript(iframeComponentId: string, label?: string): string;
/** Generate the HTML page served inside the iframe (dev / CLI-build inputs) */
export declare function generatePreviewHtml(iframeComponentId: string, css: string | Record<string, string> | null, base?: string, stage?: StageIdentityAttrs | null): string;
export interface StaticCssLink {
    href: string;
    name?: string;
    disabled?: boolean;
}
/** Generate the HTML page for a preview emitted into a host app's build. */
export declare function generateStaticPreviewHtml(scriptSrc: string, cssLinks: StaticCssLink[], base?: string): string;
export interface ParsedSnippetId {
    docFilePath: string;
    entitySlug: string;
    snippetSlug: string;
    /** The decoded doc path, leading `../` stripped — for suffix matching when
     * the caller encoded against a different root. */
    relPath?: string;
}
/**
 * Svelte `compilerOptions.warningFilter` for sdocs' generated modules.
 *
 * Two diagnostics are about markup and CSS the `.sdoc` author never wrote and
 * can't change, so reporting them only buries the warnings that matter:
 *
 * - `css_unused_selector` in any generated module. A file-level `<style>` is
 *   documented as CSS for the file's stages, and the same block is injected
 *   into every stage *and* into the DOC/PAGE component. In the stages it's a
 *   global `{@html}` block; in the page component it's a real scoped style,
 *   so every stage-targeting selector is correctly "unused" there — a warning
 *   about markup that lives in another compilation unit.
 * - `a11y_no_noninteractive_tabindex` in a generated **page** module. Prose
 *   is rendered by sdocs' markdown pipeline, and shiki emits
 *   `<pre tabindex="0">` — which is the a11y-correct thing for a scrollable
 *   code block, and comes from us, not the author.
 *
 * Everything else survives, and the project's own components keep every
 * warning they'd normally get.
 */
export declare function sdocsWarningFilter(warning: {
    code: string;
    filename?: string;
}): boolean;
/** Build the virtual module ID for an iframe wrapper component */
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, 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 natively-rendered body: a DOC or PAGE entity's
 * content, or one [PROSE] block of a SHOWCASE (slug `prose-1`, `prose-2`, …) */
export declare function pageVirtualId(docFilePath: string, entitySlug: string, slug?: string): string;
/** Parse a page virtual ID back into its parts */
export declare function parsePageId(id: string): {
    docFilePath: string;
    entitySlug: string;
    slug: 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 */
export declare function parseMountId(id: string): ParsedSnippetId | null;
/** Parse an iframe virtual ID back into its parts */
export declare function parseIframeId(id: string): ParsedSnippetId | null;
/** Parse a preview URL back into its parts */
export declare function parsePreviewUrl(url: string): ParsedSnippetId | null;