docmedown 0.1.7 → 0.9.0

package/dist/types/runtime/markdown/tables.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Table rendering and export helpers.
+ *
+ * Both GFM pipe tables and ```csv / ```tsv fences render through
+ * `renderTableBlock`, so they share one structure: a slim toolbar (caption +
+ * "Copy" dropdown) above a scrollable `<table>`. The export functions work on
+ * plain `TableData` read back from the rendered DOM, so what you copy is what
+ * you see regardless of the source format.
+ */
+export type TableAlign = "left" | "center" | "right" | null;
+export interface TableCell {
+    /** Ready-to-insert HTML for the cell. */
+    html: string;
+    align?: TableAlign;
+}
+export interface TableData {
+    /** Plain-text header cells. Empty when the table has no header row. */
+    headers: string[];
+    rows: string[][];
+    aligns: TableAlign[];
+}
+export declare const TABLE_COPY_FORMATS: readonly [{
+    readonly id: "markdown";
+    readonly label: "Markdown";
+    readonly badge: "MD";
+    readonly description: "For documents";
+}, {
+    readonly id: "html";
+    readonly label: "HTML";
+    readonly badge: "&lt;&gt;";
+    readonly description: "For web pages";
+}, {
+    readonly id: "csv";
+    readonly label: "CSV";
+    readonly badge: "CSV";
+    readonly description: "For spreadsheets";
+}];
+export type TableCopyFormat = (typeof TABLE_COPY_FORMATS)[number]["id"];
+/** Builds the full table block markup (toolbar + scroll wrapper + table). */
+export declare function renderTableBlock(options: {
+    header: TableCell[] | null;
+    rows: TableCell[][];
+    caption?: string;
+}): string;
+/** Resolves a `delimiter=` option (`;`, `tab`, `pipe`, …). */
+export declare function resolveDelimiter(value: string | undefined, fallback: string): string;
+/** Picks the most frequent candidate delimiter on the first non-empty line. */
+export declare function detectDelimiter(text: string): string;
+/**
+ * RFC 4180-style parser: quoted fields, escaped quotes (`""`), delimiters and
+ * newlines inside quotes, CRLF or LF row breaks. Blank lines are skipped.
+ */
+export declare function parseDelimited(text: string, delimiter?: string): string[][];
+/**
+ * Renders a ```csv / ```tsv fence as a table block.
+ *
+ * Fence options: `title="Caption"`, `header=false`, `delimiter=";"|tab|pipe`
+ * (CSV auto-detects `, ; tab |` when omitted), `markdown=true` to parse cells
+ * as inline Markdown (cells are plain text by default so data stays literal).
+ * Columns that are entirely numeric are right-aligned.
+ */
+export declare function renderDelimitedBlock(code: string, infoString: string, lang: "csv" | "tsv", renderInline: (source: string) => string): string;
+export declare function tableToCsv(data: TableData): string;
+export declare function tableToMarkdown(data: TableData): string;
+export declare function tableToHtml(data: TableData): string;
+export declare function formatTable(data: TableData, format: TableCopyFormat): string;
+/** Reads plain-text table data back out of a rendered `.dmd-table-block`. */
+export declare function readTableData(table: HTMLTableElement): TableData;

package/dist/types/runtime/media.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Media detection, MIME type resolution, and lossless embedding utilities
+ * for DocMeDown's <Media /> component and offline distributables.
+ */
+export type MediaCategory = "image" | "vector" | "video" | "audio" | "unknown";
+export declare const MEDIA_MIME_TYPES: Record<string, string>;
+/** Extracts extension without dot, query params or hash fragments. */
+export declare function extractExtension(urlOrPath: string): string;
+/** Determines MIME type from file extension or explicit type hint. */
+export declare function resolveMimeType(urlOrPath: string, explicitType?: string): string;
+/**
+ * Categorizes media into "image" (raster), "vector" (SVG), "video", or "audio".
+ */
+export declare function detectMediaCategory(urlOrPath: string, typeOrFormat?: string): MediaCategory;
+/** True if the target URL or path appears to reference a known media asset. */
+export declare function isMediaFile(urlOrPath: string): boolean;
+/** True if a string is a valid Data URI. */
+export declare function isDataUri(url: string): boolean;
+/** Parses a Data URI into its MIME type, base64 status, and payload. */
+export declare function parseDataUri(dataUri: string): {
+    mimeType: string;
+    isBase64: boolean;
+    data: string;
+} | null;
+/**
+ * Encodes binary bytes losslessly to a Base64 Data URI.
+ * This conversion is 100% bijective and preserves the original bitstream
+ * without lossy compression or transcoding.
+ */
+export declare function toLosslessDataUri(bytes: Uint8Array | ArrayBuffer | string, mimeType: string): string;

package/dist/types/runtime/motion.d.ts

@@ -0,0 +1,134 @@
+/**
+ * DocMeDown Performance-Minded Motion & Animation Engine.
+ *
+ * Built on top of motion/mini (lightweight WAAPI) with:
+ * - Native prefers-reduced-motion support (zero duration for accessibility).
+ * - Interruptible, cancelable smooth scrolling for Carousels.
+ * - Hardware-accelerated transitions for Tabs and Accordions.
+ * - Svelte actions (motion, fade, slide, scale) and React hooks (useMotion)
+ *   for effortless custom component animations.
+ */
+import { animate as motionAnimate } from "motion/mini";
+export { motionAnimate as animateRaw };
+/**
+ * Checks whether the target is a real browser DOM Element.
+ * Protects against crashes in SSR/prerendering and mock test environments.
+ */
+export declare function isDOMElement(target: unknown): target is Element;
+/**
+ * Checks whether the user has requested "Reduce motion".
+ * Respects explicit user overrides (data-dmd-motion or localStorage) while
+ * preserving DocMeDown's performance-minded subtle animations by default.
+ */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * Normalizes motion options based on the user's motion preferences.
+ */
+export declare function getMotionOptions<T extends {
+    duration?: number;
+    delay?: number;
+}>(options: T): T;
+/**
+ * Safe, accessibility-respecting wrapper around motion's animate function.
+ */
+export declare function animate(target: any, keyframes: Record<string, any>, options?: Record<string, any>): (Promise<void> & {
+    stop: () => void;
+}) | import("motion-dom").AnimationPlaybackControlsWithThen;
+export interface SmoothScrollOptions {
+    duration?: number;
+    direction?: "x" | "y";
+    easing?: (t: number) => number;
+    onComplete?: () => void;
+}
+/**
+ * Smoothly and cancelably animates scrollLeft or scrollTop of a container.
+ * Automatically interrupts any active animation on subsequent user clicks.
+ */
+export declare function smoothScroll(container: HTMLElement, targetOffset: number, options?: SmoothScrollOptions): {
+    stop: () => void;
+    finished: Promise<void>;
+};
+export interface DisclosureAnimationOptions {
+    duration?: number;
+    onComplete?: () => void;
+}
+/**
+ * Expands an element smoothly from 0px (or its current height) to its natural scrollHeight.
+ */
+export declare function expand(element: HTMLElement, options?: DisclosureAnimationOptions): {
+    stop: () => void;
+    finished: Promise<void>;
+};
+/**
+ * Collapses an element smoothly from its current height down to 0px.
+ */
+export declare function collapse(element: HTMLElement, options?: DisclosureAnimationOptions): {
+    stop: () => void;
+    finished: Promise<void>;
+};
+export interface MotionOptions {
+    initial?: Record<string, any>;
+    animate?: Record<string, any>;
+    transition?: {
+        duration?: number;
+        delay?: number;
+        ease?: any;
+    };
+    inView?: boolean;
+}
+/** Options shared by the fade, slide, and scale Svelte action presets. Durations are seconds. */
+export interface MotionPresetOptions {
+    duration?: number;
+    delay?: number;
+    inView?: boolean;
+}
+/**
+ * Svelte action for declarative component animations:
+ * `<div use:motion={{ initial: { opacity: 0, y: 15 }, animate: { opacity: 1, y: 0 } }}>`
+ */
+export declare function motion(node: HTMLElement, options?: MotionOptions): {
+    update(newOptions: MotionOptions): void;
+    destroy(): void;
+};
+/**
+ * Svelte action preset for smooth fade-in.
+ */
+export declare function fade(node: HTMLElement, options?: MotionPresetOptions): {
+    update: (value: typeof options) => void;
+    destroy: () => void;
+};
+/**
+ * Svelte action preset for smooth slide-in.
+ */
+export declare function slide(node: HTMLElement, options?: MotionPresetOptions & {
+    direction?: "up" | "down" | "left" | "right";
+    distance?: number;
+}): {
+    update: (value: typeof options) => void;
+    destroy: () => void;
+};
+/**
+ * Svelte action preset for smooth scale-in.
+ */
+export declare function scale(node: HTMLElement, options?: MotionPresetOptions & {
+    from?: number;
+}): {
+    update: (value: typeof options) => void;
+    destroy: () => void;
+};
+/**
+ * React ref callback hook for animating elements in React custom components:
+ * `const ref = useMotion({ initial: { opacity: 0 }, animate: { opacity: 1 } });`
+ */
+export declare function useMotion<T extends HTMLElement = HTMLElement>(options?: MotionOptions): (element: T | null) => void;
+/**
+ * Animates a list of elements with sequential stagger delays.
+ */
+export declare function stagger<T extends Element = Element>(elements: ArrayLike<T> | Iterable<T>, keyframes: Record<string, any>, options?: {
+    duration?: number;
+    staggerDelay?: number;
+    delay?: number;
+    ease?: any;
+}): ((Promise<void> & {
+    stop: () => void;
+}) | import("motion-dom").AnimationPlaybackControlsWithThen)[];

package/dist/types/runtime/offline-export.d.ts

@@ -1,11 +1,13 @@
+import { type SplashOptions } from "./splash";
 import type { DocManifest } from "./types";
-export declare const OFFLINE_FORMAT_VERSION = 1;
+export declare const OFFLINE_FORMAT_VERSION = 2;
 export declare const OFFLINE_RUNTIME_SCRIPT_ATTRIBUTE = "data-docmedown-runtime";
 export interface OfflineDocumentationData {
     manifest: DocManifest;
     docs: Record<string, string>;
     componentsSource?: string;
     nestedSites?: Record<string, OfflineNestedSiteData>;
+    media?: Record<string, string>;
 }
 /** A nested documentation root embedded inside a parent offline bundle. */
 export interface OfflineNestedSiteData {
@@ -13,6 +15,7 @@ export interface OfflineNestedSiteData {
     manifest: DocManifest;
     docs: Record<string, string>;
     componentsSource?: string;
+    media?: Record<string, string>;
 }
 /** Emitted when a reader selects a file link a self-contained copy cannot fulfill. */
 export declare const OFFLINE_LINK_EVENT = "docmedown:offline-link-unavailable";
@@ -30,8 +33,12 @@ export declare function notifyUnavailableOfflineLink(message?: string): void;
  * Generates the tiny self-extracting HTML shell shared by CLI and browser
  * exporters. The payload is a base64-encoded gzip stream containing compact
  * JSON with documentation data and the minified IIFE runtime.
+ *
+ * The shell carries the same inline splash as served pages, so an offline copy
+ * opens on the branded loader instead of a blank canvas while the runtime is
+ * decompressed and booted.
  */
-export declare function createCompressedOfflineHtml(encodedGzip: string, title: string): string;
+export declare function createCompressedOfflineHtml(encodedGzip: string, title: string, splash?: SplashOptions, favicon?: string): string;
 export declare function createOfflineDownload(): Promise<{
     blob: Blob;
     filename: string;

package/dist/types/runtime/router.d.ts

@@ -3,9 +3,24 @@ export interface RouteInfo {
     anchor: string;
     fullPath: string;
 }
+/** Globals injected by the static-site prerenderer into every generated page. */
+export interface StaticRuntimeContext {
+    /** Relative prefix from the current page to site-root assets, e.g. "../..". Empty at the site root. */
+    base: string;
+    /** Slug of the document the current page was prerendered from. */
+    slug: string;
+}
+export declare function getStaticRuntimeContext(): StaticRuntimeContext | null;
+export declare function scrollToAndHighlight(element: HTMLElement): void;
+/** True when the current page was prerendered by the static site build. */
+export declare function isStaticRuntime(): boolean;
+/** Creates the router appropriate for the current page: pathname routes for prerendered builds, hash routes otherwise. */
+export declare function createRouter(defaultDoc?: string): HashRouter;
+/** Joins a site-root-relative asset prefix with a file name ("../..", "_docs.js" → "../../_docs.js"). */
+export declare function joinStaticBase(base: string, file: string): string;
 export declare class HashRouter {
-    private listeners;
-    private defaultDoc;
+    protected listeners: Set<(route: RouteInfo) => void>;
+    protected defaultDoc: string;
     constructor(defaultDoc?: string);
     destroy(): void;
     setDefaultDoc(defaultDoc: string): void;
@@ -15,9 +30,32 @@ export declare class HashRouter {
     navigate(path: string, anchor?: string): void;
     scrollToAnchor(anchorId: string): void;
     subscribe(callback: (route: RouteInfo) => void): () => void;
+    protected emitRoute(route: RouteInfo): void;
     private handleHashChange;
     /**
      * Resolves a relative markdown link into a hash navigation target
      */
     resolveLink(href: string, currentSlug: string): string;
 }
+/**
+ * Path router used by prerendered static builds. The public URL scheme is
+ * `<base>/<slug>/` (README → `<base>/`); heading anchors stay in the URL
+ * hash. The engine API (navigate/subscribe/resolveLink) is identical to
+ * HashRouter, so application code never needs to know which one is active.
+ */
+export declare class StaticRouter extends HashRouter {
+    private urlBase;
+    constructor(defaultDoc?: string);
+    destroy(): void;
+    getCurrentRoute(): RouteInfo;
+    /** Maps a static page pathname + hash onto a route. */
+    parseStaticPath(pathname: string, rawHash: string): RouteInfo;
+    /** Builds the canonical URL for a document slug, including the site base when present. */
+    urlForSlug(slug: string, anchor?: string): string;
+    navigate(path: string, anchor?: string): void;
+    scrollToAnchor(anchorId: string): void;
+    /** Resolves relative markdown links onto canonical page URLs instead of hash routes. */
+    resolveLink(href: string, currentSlug: string): string;
+    private parseStaticAnchor;
+    private handlePopState;
+}

package/dist/types/runtime/splash.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Branded app-shell splash shown while the runtime boots.
+ *
+ * The runtime stylesheet is injected by JavaScript, so before the bundle runs
+ * the page is otherwise unstyled (a blank white canvas). The splash ships as
+ * inline critical CSS plus a tiny theme bootstrap inside each shell —
+ * prerendered pages, the standard template, the dev-server fallback, and
+ * offline copies — so it paints immediately, matches the saved theme and color
+ * mode (no light flash), holds for a minimum brand beat, then hands off to the
+ * first document.
+ *
+ * The overlay is a pixel-faithful preview of the real reader chrome rather
+ * than an abstract loader: a 68px-class top bar (--dmd-splash-navh) with the
+ * brand lockup, search field, and action chips; a sidebar-rail skeleton with
+ * labeled section groups and an active entry; an article skeleton with the
+ * breadcrumb row, document title, meta rule, callout, and code-block rhythms
+ * of a real page; and a table-of-contents rail on wide viewports. Column
+ * widths, type, spacing, radii, and breakpoints mirror `main.css` (TOC folds
+ * into a card at 1280px, search collapses to an icon at 1100px, the sidebar
+ * rail retires at 1024px, compact bar under 680px), so the mounted app lands
+ * on identically-proportioned chrome and dismissal reads as one crossfade
+ * rather than a blank-to-content jump.
+ *
+ * Everything here must stay dependency-free and inline: it runs before any
+ * stylesheet or module is available. Keep the output small — it is embedded in
+ * every generated page and, for `file://` copies, is not gzip-compressed.
+ */
+export declare const SPLASH_ID = "dmd-splash";
+export declare const SPLASH_HIDDEN_CLASS = "dmd-splash-hidden";
+/** Marks <html> while the splash is up so the page behind cannot scroll. */
+export declare const SPLASH_ACTIVE_CLASS = "dmd-splash-active";
+/** Records the first-paint timestamp so the splash can hold for a minimum time. */
+export declare const SPLASH_START_KEY = "__DOCMEDOWN_SPLASH_START__";
+/** Minimum brand time before the splash may be dismissed, in milliseconds. */
+export declare const SPLASH_MIN_DURATION_MS = 950;
+/** Must match the `#dmd-splash` transition duration in the stylesheet below. */
+export declare const SPLASH_EXIT_MS = 450;
+export interface SplashOptions {
+    /** Documentation name rendered in the top-bar brand lockup. */
+    name?: string;
+    /**
+     * Optional one-line description (from `docs.json` `tagline`). Rendered as
+     * the article preview's real description line so the shell reads branded
+     * instead of fully grey — omitted when not provided.
+     */
+    tagline?: string;
+    /** Optional version string rendered as a pill next to the brand name. */
+    version?: string;
+    /** Optional brand logo URL (`theme.logo.light`). Takes precedence over the mark. */
+    logo?: string;
+    /** Optional brand logo URL for dark mode (`theme.logo.dark`). */
+    logoDark?: string;
+    /** Alt text for the brand logo. Falls back to the documentation name. */
+    logoAlt?: string;
+    /**
+     * Brand accent override for light mode (from `docs.json`
+     * `theme.accentColor`). The runtime applies the same override once booted;
+     * the splash needs it inlined because it paints first. Only `#hex` forms
+     * are accepted — anything else is ignored, so a stray config value can
+     * never inject markup or CSS.
+     */
+    accent?: string;
+    /** Brand accent override for dark mode (`theme.accentColorDark`). */
+    accentDark?: string;
+    /** Optional search bar placeholder text (from `docs.json` `search.placeholder`). */
+    searchPlaceholder?: string;
+}
+/**
+ * Head fragment for a shell: splash styles, an optional brand-accent override,
+ * the theme bootstrap (which also carries the failsafe and the `SPLASH_EXIT_MS`
+ * removal delay), and a `<noscript>` fallback so JS-disabled readers (and
+ * crawlers) get the prerendered content instead of a permanent splash.
+ */
+export declare function renderSplashHead(options?: SplashOptions): string;
+/**
+ * Body markup for the splash overlay: a preview of the reader shell (top bar,
+ * navigation, article, table of contents) in the same proportions as the app,
+ * so the first real paint lands where the skeleton already is. Skeleton
+ * regions are `aria-hidden` — the root keeps a single `role="status"` live
+ * message — and the visible title/description are real text.
+ */
+export declare function renderSplashMarkup({ name, tagline, version, logo, logoDark, logoAlt, searchPlaceholder, }?: SplashOptions): string;
+/**
+ * Retires the splash once the app has content to show — but never before
+ * `SPLASH_MIN_DURATION_MS` has elapsed since first paint, so a fast load still
+ * gets a consistent brand beat instead of a sub-frame flash. The reveal
+ * crossfades the splash out while the page fades in (see the
+ * `html.dmd-splash-active` rule in main.css).
+ */
+export declare function dismissSplash(): void;

package/dist/types/runtime/svelte-compiler-engine.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/runtime/svelte-compiler-loader.d.ts

@@ -0,0 +1,14 @@
+/**
+ * On-demand loader for the Svelte compiler engine (`docmedown-compiler.js`).
+ *
+ * Like Mermaid, the Svelte compiler (~800 KB minified) is externalized into an
+ * on-demand engine bundle and loaded only when dynamic in-browser `.svelte`
+ * compilation is required.
+ */
+export interface SvelteCompilerEngine {
+    compile: typeof import("svelte/compiler").compile;
+}
+export declare function configureCompilerEngine(basePath?: string): void;
+export declare function loadExternalCompilerEngine(): Promise<SvelteCompilerEngine>;
+/** Resolves the Svelte compiler engine once, from the external bundle or a dynamic import. */
+export declare function loadCompilerEngine(): Promise<SvelteCompilerEngine>;

package/dist/types/runtime/svelte-runtime.d.ts

@@ -0,0 +1,29 @@
+import { ensureCustomElementTag } from "./svelte-tag";
+export { ensureCustomElementTag };
+export interface CompiledSvelteResult {
+    js: string;
+    css?: string;
+    tag: string;
+}
+/**
+ * Rewrites bare `svelte` and `svelte/internal/client` ESM imports to use the
+ * globally exposed Svelte 5 runtime primitives when evaluated as a Blob module.
+ */
+export declare function linkSveltePrimitives(jsCode: string): string;
+/**
+ * Compiles a raw `.svelte` source string into client JavaScript with custom element registration.
+ */
+export declare function compileSvelteComponent(source: string, options: {
+    name: string;
+    tag?: string;
+    filename?: string;
+}): Promise<CompiledSvelteResult>;
+/**
+ * Evaluates compiled Svelte 5 component JavaScript in the browser as a Blob module.
+ * The module automatically invokes `customElements.define()` upon execution.
+ */
+export declare function evaluateCompiledSvelte(jsCode: string): Promise<unknown>;
+/**
+ * Fetches, compiles, and registers a remote or local `.svelte` component on the fly.
+ */
+export declare function loadAndRegisterSvelteComponent(url: string, name: string): Promise<string>;

package/dist/types/runtime/svelte-tag.d.ts

@@ -0,0 +1,7 @@
+export declare function toKebab(name: string): string;
+/** Canonical custom element tag for a component name: "CounterWidget" → "dmd-counter-widget". */
+export declare function dmdTag(name: string): string;
+/**
+ * Ensures a Svelte 5 component template carries a customElement definition tag.
+ */
+export declare function ensureCustomElementTag(source: string, tagName: string): string;

package/dist/types/runtime/ts-compiler.d.ts

@@ -0,0 +1,24 @@
+/**
+ * In-browser and Node TypeScript/TSX dynamic compiler for DocMeDown.
+ *
+ * Transforms React TSX/JSX and TypeScript modules into standard ES modules,
+ * enabling dynamic component compilation directly in modern browsers.
+ */
+export interface CompileTsxOptions {
+    filename?: string;
+    jsxFactory?: string;
+    jsxFragment?: string;
+    useCache?: boolean;
+}
+/**
+ * Strips TypeScript types and transforms JSX tags using a lightweight regex/AST parser.
+ * Used when a heavy WebAssembly/worker compiler is not yet loaded in browser.
+ */
+export declare function lightweightTransformTsx(source: string, options?: {
+    jsxFactory?: string;
+    jsxFragment?: string;
+}): string;
+/**
+ * Compiles a TSX or TypeScript source string into standard executable JavaScript.
+ */
+export declare function compileTsx(source: string, options?: CompileTsxOptions): Promise<string>;

package/dist/types/runtime/types.d.ts

@@ -72,6 +72,7 @@ export interface DocManifest {
     config: DocConfig;
     docs: DocFileItem[];
     tree: SidebarTreeNode[];
+    customComponents?: string[];
 }
 export interface SidebarTreeNode {
     id: string;