From 439b2332c1341d8e8374f0ccbf868e61f5c945d2 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sat, 16 May 2026 12:52:55 +0000
Subject: [PATCH 1/2] feat(demo): add MDsveX /docs with
 enhanced-video-sveltekit guide

---
 apps/demo/package.json                        |   3 +
 .../src/lib/docs/DocsInstallSwitcher.svelte   |  51 ++
 .../demo/src/lib/docs/DocsVideoFeature.svelte |  17 +
 apps/demo/src/lib/mdsvex/Callout.svelte       |  32 +
 .../src/lib/mdsvex/MdsvexArticleLayout.svelte |  98 +++
 apps/demo/src/lib/mdsvex/md/MdA.svelte        |  25 +
 .../src/lib/mdsvex/md/MdBlockquote.svelte     |   5 +
 apps/demo/src/lib/mdsvex/md/MdH1.svelte       |   3 +
 apps/demo/src/lib/mdsvex/md/MdH2.svelte       |   5 +
 apps/demo/src/lib/mdsvex/md/MdH3.svelte       |   3 +
 apps/demo/src/lib/mdsvex/md/MdHr.svelte       |   1 +
 apps/demo/src/lib/mdsvex/md/MdLi.svelte       |   1 +
 apps/demo/src/lib/mdsvex/md/MdOl.svelte       |   3 +
 apps/demo/src/lib/mdsvex/md/MdP.svelte        |   1 +
 apps/demo/src/lib/mdsvex/md/MdPre.svelte      |   3 +
 apps/demo/src/lib/mdsvex/md/MdStrong.svelte   |   1 +
 apps/demo/src/lib/mdsvex/md/MdTable.svelte    |   7 +
 apps/demo/src/lib/mdsvex/md/MdTd.svelte       |   1 +
 apps/demo/src/lib/mdsvex/md/MdTh.svelte       |   5 +
 apps/demo/src/lib/mdsvex/md/MdThead.svelte    |   5 +
 apps/demo/src/lib/mdsvex/md/MdTr.svelte       |   5 +
 apps/demo/src/lib/mdsvex/md/MdUl.svelte       |   3 +
 apps/demo/src/routes/+page.svelte             |  18 +-
 apps/demo/src/routes/docs/+layout.svelte      |  44 ++
 apps/demo/src/routes/docs/+page.svx           | 187 +++++
 apps/demo/svelte.config.js                    |  28 +-
 pnpm-lock.yaml                                | 689 ++++++++++++++++++
 27 files changed, 1237 insertions(+), 7 deletions(-)
 create mode 100644 apps/demo/src/lib/docs/DocsInstallSwitcher.svelte
 create mode 100644 apps/demo/src/lib/docs/DocsVideoFeature.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/Callout.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/MdsvexArticleLayout.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdA.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdBlockquote.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdH1.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdH2.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdH3.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdHr.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdLi.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdOl.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdP.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdPre.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdStrong.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdTable.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdTd.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdTh.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdThead.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdTr.svelte
 create mode 100644 apps/demo/src/lib/mdsvex/md/MdUl.svelte
 create mode 100644 apps/demo/src/routes/docs/+layout.svelte
 create mode 100644 apps/demo/src/routes/docs/+page.svx

diff --git a/apps/demo/package.json b/apps/demo/package.json
index bc39d89..49a5784 100644
--- a/apps/demo/package.json
+++ b/apps/demo/package.json
@@ -27,6 +27,9 @@
     "bits-ui": "^2.18.1",
     "clsx": "^2.1.1",
     "enhanced-video-sveltekit": "workspace:*",
+    "mdsvex": "^0.12.7",
+    "prism-themes": "^1.9.0",
+    "remark-gfm": "^4.0.1",
     "shadcn-svelte": "^1.2.7",
     "svelte": "^5.0.0",
     "svelte-check": "^4.0.0",
diff --git a/apps/demo/src/lib/docs/DocsInstallSwitcher.svelte b/apps/demo/src/lib/docs/DocsInstallSwitcher.svelte
new file mode 100644
index 0000000..444ff78
--- /dev/null
+++ b/apps/demo/src/lib/docs/DocsInstallSwitcher.svelte
@@ -0,0 +1,51 @@
+<script lang="ts">
+	import { Badge } from '$lib/components/ui/badge/index.js';
+	import { Button } from '$lib/components/ui/button/index.js';
+	import { Card, CardContent, CardHeader } from '$lib/components/ui/card/index.js';
+	let tab = $state<'cli' | 'config'>('cli');
+</script>
+
+<div class="not-prose my-8 w-full max-w-2xl">
+	<Card class="overflow-hidden border-border/80 shadow-sm">
+		<CardHeader class="flex flex-row flex-wrap items-center gap-2 border-b border-border/60 bg-muted/30 py-3">
+			<span class="text-xs font-medium text-muted-foreground">Example</span>
+			<div class="ml-auto flex gap-1 rounded-full bg-muted p-1">
+				<Button
+					type="button"
+					size="sm"
+					variant={tab === 'cli' ? 'default' : 'ghost'}
+					class="h-8 rounded-full px-3 text-xs"
+					onclick={() => (tab = 'cli')}>CLI</Button>
+				<Button
+					type="button"
+					size="sm"
+					variant={tab === 'config' ? 'default' : 'ghost'}
+					class="h-8 rounded-full px-3 text-xs"
+					onclick={() => (tab = 'config')}>Vite</Button>
+			</div>
+		</CardHeader>
+		<CardContent class="p-0">
+			{#if tab === 'cli'}
+				<div class="space-y-3 bg-card p-5 font-mono text-[13px] leading-relaxed">
+					<div class="flex flex-wrap items-center gap-2">
+						<Badge variant="secondary" class="font-mono text-[10px]">shell</Badge>
+						<span class="text-muted-foreground">Install into a SvelteKit app</span>
+					</div>
+					<pre
+						class="m-0 overflow-x-auto rounded-xl border border-border bg-muted/40 p-4 text-foreground"
+					><code>pnpm add -D enhanced-video-sveltekit</code></pre>
+				</div>
+			{:else}
+				<div class="space-y-3 bg-card p-5 font-mono text-[13px] leading-relaxed">
+					<div class="flex flex-wrap items-center gap-2">
+						<Badge variant="secondary" class="font-mono text-[10px]">vite.config.ts</Badge>
+						<span class="text-muted-foreground">Plugin order matters</span>
+					</div>
+					<pre
+						class="m-0 overflow-x-auto rounded-xl border border-border bg-muted/40 p-4 text-foreground"
+					><code>plugins: [tailwindcss(), enhancedVideos(), sveltekit()]</code></pre>
+				</div>
+			{/if}
+		</CardContent>
+	</Card>
+</div>
diff --git a/apps/demo/src/lib/docs/DocsVideoFeature.svelte b/apps/demo/src/lib/docs/DocsVideoFeature.svelte
new file mode 100644
index 0000000..1329759
--- /dev/null
+++ b/apps/demo/src/lib/docs/DocsVideoFeature.svelte
@@ -0,0 +1,17 @@
+<section class="not-prose my-8 overflow-hidden rounded-2xl border border-border bg-card shadow-sm">
+	<div class="border-b border-border bg-muted/40 px-4 py-2.5">
+		<p class="m-0 font-mono text-[11px] font-medium uppercase tracking-wider text-muted-foreground">
+			Live clip (build pipeline)
+		</p>
+	</div>
+	<enhanced:video
+		src="$lib/coverr-the-perfect-wave-2027-1080p.mp4"
+		autoplay
+		muted
+		loop
+		playsinline
+		loading="eager"
+		class="block w-full bg-black"
+		style="aspect-ratio: 16 / 9"
+	></enhanced:video>
+</section>
diff --git a/apps/demo/src/lib/mdsvex/Callout.svelte b/apps/demo/src/lib/mdsvex/Callout.svelte
new file mode 100644
index 0000000..1695c0e
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/Callout.svelte
@@ -0,0 +1,32 @@
+<script lang="ts">
+	import * as Alert from '$lib/components/ui/alert/index.js';
+	import { cn } from '$lib/utils.js';
+	import type { Snippet } from 'svelte';
+
+	type Tone = 'info' | 'success' | 'warning';
+
+	let {
+		title,
+		tone = 'info',
+		class: className,
+		children
+	}: {
+		title: string;
+		tone?: Tone;
+		class?: string;
+		children: Snippet;
+	} = $props();
+
+	const shell = {
+		info: 'border-primary/25 bg-primary/[0.04] dark:bg-primary/[0.08]',
+		success: 'border-emerald-500/30 bg-emerald-500/[0.06] dark:bg-emerald-500/[0.1]',
+		warning: 'border-amber-500/35 bg-amber-500/[0.07] dark:bg-amber-500/[0.12]'
+	} satisfies Record<Tone, string>;
+</script>
+
+<Alert.Root class={cn('not-prose my-6 rounded-2xl', shell[tone], className)}>
+	<Alert.Title>{title}</Alert.Title>
+	<Alert.Description class="text-[15px] leading-relaxed">
+		{@render children()}
+	</Alert.Description>
+</Alert.Root>
diff --git a/apps/demo/src/lib/mdsvex/MdsvexArticleLayout.svelte b/apps/demo/src/lib/mdsvex/MdsvexArticleLayout.svelte
new file mode 100644
index 0000000..310ad67
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/MdsvexArticleLayout.svelte
@@ -0,0 +1,98 @@
+<script module lang="ts">
+	import MdA from './md/MdA.svelte';
+	import MdBlockquote from './md/MdBlockquote.svelte';
+	import MdH1 from './md/MdH1.svelte';
+	import MdH2 from './md/MdH2.svelte';
+	import MdH3 from './md/MdH3.svelte';
+	import MdHr from './md/MdHr.svelte';
+	import MdLi from './md/MdLi.svelte';
+	import MdOl from './md/MdOl.svelte';
+	import MdP from './md/MdP.svelte';
+	import MdPre from './md/MdPre.svelte';
+	import MdStrong from './md/MdStrong.svelte';
+	import MdTable from './md/MdTable.svelte';
+	import MdTd from './md/MdTd.svelte';
+	import MdTh from './md/MdTh.svelte';
+	import MdThead from './md/MdThead.svelte';
+	import MdTr from './md/MdTr.svelte';
+	import MdUl from './md/MdUl.svelte';
+
+	export {
+		MdA as a,
+		MdBlockquote as blockquote,
+		MdH1 as h1,
+		MdH2 as h2,
+		MdH3 as h3,
+		MdHr as hr,
+		MdLi as li,
+		MdOl as ol,
+		MdP as p,
+		MdPre as pre,
+		MdStrong as strong,
+		MdTable as table,
+		MdTd as td,
+		MdTh as th,
+		MdThead as thead,
+		MdTr as tr,
+		MdUl as ul
+	};
+</script>
+
+<script lang="ts">
+	import 'prism-themes/themes/prism-one-light.css';
+	import { Badge } from '$lib/components/ui/badge/index.js';
+	import { Separator } from '$lib/components/ui/separator/index.js';
+	import { cn } from '$lib/utils.js';
+	import type { Snippet } from 'svelte';
+
+	let {
+		title = 'Documentation',
+		description = '',
+		updated,
+		children
+	}: {
+		title?: string;
+		description?: string;
+		updated?: string;
+		children: Snippet;
+	} = $props();
+</script>
+
+<article
+	class={cn(
+		'mx-auto w-full max-w-[min(100%,52rem)]',
+		'prose prose-neutral max-w-none dark:prose-invert',
+		'prose-headings:scroll-mt-24 prose-headings:font-semibold prose-headings:tracking-tight',
+		'prose-p:leading-relaxed prose-li:leading-relaxed',
+		'prose-pre:bg-transparent prose-pre:p-0'
+	)}
+>
+	<header class="not-prose mb-10 space-y-3 border-b border-border pb-8">
+		<div class="flex flex-wrap items-center gap-2">
+			<Badge variant="secondary" class="rounded-full px-2.5 font-mono text-[11px] uppercase tracking-wider">
+				SvelteKit
+			</Badge>
+			<Badge variant="outline" class="rounded-full px-2.5 font-mono text-[11px] uppercase tracking-wider">
+				Vite
+			</Badge>
+		</div>
+		<h1 class="m-0 text-balance text-3xl font-semibold tracking-tight sm:text-4xl">{title}</h1>
+		{#if description}
+			<p class="m-0 max-w-2xl text-base text-muted-foreground">{description}</p>
+		{/if}
+		{#if updated}
+			<p class="m-0 text-xs text-muted-foreground">Last updated <time datetime={updated}>{updated}</time></p>
+		{/if}
+	</header>
+
+	<div class="mdsvex-body">
+		{@render children()}
+	</div>
+
+	<Separator class="not-prose my-14" />
+
+	<footer class="not-prose flex flex-col gap-2 text-sm text-muted-foreground sm:flex-row sm:items-center sm:justify-between">
+		<span>Written in MDsveX; examples use shadcn-svelte.</span>
+		<a class="font-medium text-primary hover:underline" href="/">← Back to demo</a>
+	</footer>
+</article>
diff --git a/apps/demo/src/lib/mdsvex/md/MdA.svelte b/apps/demo/src/lib/mdsvex/md/MdA.svelte
new file mode 100644
index 0000000..e25b7b1
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdA.svelte
@@ -0,0 +1,25 @@
+<script lang="ts">
+	import type { HTMLAnchorAttributes } from 'svelte/elements';
+	import type { Snippet } from 'svelte';
+	import { cn } from '$lib/utils.js';
+
+	let {
+		class: className,
+		href,
+		children,
+		...rest
+	}: HTMLAnchorAttributes & { children?: Snippet } = $props();
+</script>
+
+<a
+	{href}
+	class={cn(
+		'font-medium text-primary underline decoration-primary/30 underline-offset-4 transition-colors hover:decoration-primary',
+		className
+	)}
+	target={typeof href === 'string' && href.startsWith('http') ? '_blank' : undefined}
+	rel={typeof href === 'string' && href.startsWith('http') ? 'noopener noreferrer' : undefined}
+	{...rest}
+>
+	{#if children}{@render children()}{/if}
+</a>
diff --git a/apps/demo/src/lib/mdsvex/md/MdBlockquote.svelte b/apps/demo/src/lib/mdsvex/md/MdBlockquote.svelte
new file mode 100644
index 0000000..2adf9db
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdBlockquote.svelte
@@ -0,0 +1,5 @@
+<blockquote
+	class="not-prose my-6 rounded-2xl border border-primary/20 bg-gradient-to-br from-primary/[0.06] to-transparent px-5 py-4 text-[15px] leading-relaxed text-muted-foreground shadow-[inset_0_1px_0_0_oklch(1_0_0_/_0.06)] dark:from-primary/[0.12]"
+>
+	<slot />
+</blockquote>
diff --git a/apps/demo/src/lib/mdsvex/md/MdH1.svelte b/apps/demo/src/lib/mdsvex/md/MdH1.svelte
new file mode 100644
index 0000000..3f34d6b
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdH1.svelte
@@ -0,0 +1,3 @@
+<h1 class="not-prose mb-4 text-balance text-3xl font-semibold tracking-tight text-foreground sm:text-[2rem]">
+	<slot />
+</h1>
diff --git a/apps/demo/src/lib/mdsvex/md/MdH2.svelte b/apps/demo/src/lib/mdsvex/md/MdH2.svelte
new file mode 100644
index 0000000..efa94a4
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdH2.svelte
@@ -0,0 +1,5 @@
+<h2
+	class="not-prose mb-3 mt-10 scroll-mt-24 border-b border-border pb-2 text-xl font-semibold tracking-tight text-foreground first:mt-0 sm:text-2xl"
+>
+	<slot />
+</h2>
diff --git a/apps/demo/src/lib/mdsvex/md/MdH3.svelte b/apps/demo/src/lib/mdsvex/md/MdH3.svelte
new file mode 100644
index 0000000..8d986bf
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdH3.svelte
@@ -0,0 +1,3 @@
+<h3 class="not-prose mb-2 mt-8 scroll-mt-20 text-lg font-semibold tracking-tight text-foreground sm:text-xl">
+	<slot />
+</h3>
diff --git a/apps/demo/src/lib/mdsvex/md/MdHr.svelte b/apps/demo/src/lib/mdsvex/md/MdHr.svelte
new file mode 100644
index 0000000..8db62d6
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdHr.svelte
@@ -0,0 +1 @@
+<hr class="not-prose my-10 border-0 bg-gradient-to-r from-transparent via-border to-transparent" style="height: 1px" />
diff --git a/apps/demo/src/lib/mdsvex/md/MdLi.svelte b/apps/demo/src/lib/mdsvex/md/MdLi.svelte
new file mode 100644
index 0000000..49be709
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdLi.svelte
@@ -0,0 +1 @@
+<li class="text-[15px] leading-relaxed text-foreground/90 marker:text-primary"><slot /></li>
diff --git a/apps/demo/src/lib/mdsvex/md/MdOl.svelte b/apps/demo/src/lib/mdsvex/md/MdOl.svelte
new file mode 100644
index 0000000..a5a82bd
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdOl.svelte
@@ -0,0 +1,3 @@
+<ol class="not-prose my-4 list-decimal space-y-2 pl-6 marker:font-semibold marker:text-primary">
+	<slot />
+</ol>
diff --git a/apps/demo/src/lib/mdsvex/md/MdP.svelte b/apps/demo/src/lib/mdsvex/md/MdP.svelte
new file mode 100644
index 0000000..377ff67
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdP.svelte
@@ -0,0 +1 @@
+<p class="mb-4 text-[15px] leading-relaxed text-foreground/90 last:mb-0"><slot /></p>
diff --git a/apps/demo/src/lib/mdsvex/md/MdPre.svelte b/apps/demo/src/lib/mdsvex/md/MdPre.svelte
new file mode 100644
index 0000000..5505124
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdPre.svelte
@@ -0,0 +1,3 @@
+<pre
+	class="not-prose my-6 overflow-x-auto rounded-2xl border border-[hsl(230_10%_88%)] bg-[hsl(230_1%_98%)] p-4 text-[13px] leading-relaxed shadow-[0_1px_2px_hsla(230_8%_24%_/_0.06)] [&_code]:!bg-transparent [&_code]:!p-0 [&_code]:!shadow-none"
+><slot /></pre>
diff --git a/apps/demo/src/lib/mdsvex/md/MdStrong.svelte b/apps/demo/src/lib/mdsvex/md/MdStrong.svelte
new file mode 100644
index 0000000..5fdbce5
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdStrong.svelte
@@ -0,0 +1 @@
+<strong class="font-semibold text-foreground"><slot /></strong>
diff --git a/apps/demo/src/lib/mdsvex/md/MdTable.svelte b/apps/demo/src/lib/mdsvex/md/MdTable.svelte
new file mode 100644
index 0000000..766607c
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdTable.svelte
@@ -0,0 +1,7 @@
+<div
+	class="not-prose my-6 overflow-x-auto rounded-2xl border border-[hsl(230_10%_88%)] bg-[hsl(230_1%_99%)] shadow-[0_1px_2px_hsla(230_8%_24%_/_0.06)] ring-1 ring-[hsl(230_8%_24%_/_0.04)]"
+>
+	<table class="w-full min-w-[20rem] border-collapse text-left text-sm text-[hsl(230_8%_20%)]">
+		<slot />
+	</table>
+</div>
diff --git a/apps/demo/src/lib/mdsvex/md/MdTd.svelte b/apps/demo/src/lib/mdsvex/md/MdTd.svelte
new file mode 100644
index 0000000..aab62a4
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdTd.svelte
@@ -0,0 +1 @@
+<td class="px-4 py-3 align-top text-[hsl(230_6%_32%)]"><slot /></td>
diff --git a/apps/demo/src/lib/mdsvex/md/MdTh.svelte b/apps/demo/src/lib/mdsvex/md/MdTh.svelte
new file mode 100644
index 0000000..338a22a
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdTh.svelte
@@ -0,0 +1,5 @@
+<th
+	class="whitespace-nowrap px-4 py-3 font-semibold text-[hsl(230_8%_16%)] first:rounded-tl-2xl last:rounded-tr-2xl"
+>
+	<slot />
+</th>
diff --git a/apps/demo/src/lib/mdsvex/md/MdThead.svelte b/apps/demo/src/lib/mdsvex/md/MdThead.svelte
new file mode 100644
index 0000000..04e65d2
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdThead.svelte
@@ -0,0 +1,5 @@
+<thead
+	class="border-b border-[hsl(230_10%_88%)] bg-[hsl(230_15%_96%)] text-xs font-semibold uppercase tracking-wide text-[hsl(230_6%_40%)]"
+>
+	<slot />
+</thead>
diff --git a/apps/demo/src/lib/mdsvex/md/MdTr.svelte b/apps/demo/src/lib/mdsvex/md/MdTr.svelte
new file mode 100644
index 0000000..f41e05a
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdTr.svelte
@@ -0,0 +1,5 @@
+<tr
+	class="border-b border-[hsl(230_10%_92%)] transition-colors last:border-0 hover:bg-[hsl(230_40%_98%)]"
+>
+	<slot />
+</tr>
diff --git a/apps/demo/src/lib/mdsvex/md/MdUl.svelte b/apps/demo/src/lib/mdsvex/md/MdUl.svelte
new file mode 100644
index 0000000..05aa7ff
--- /dev/null
+++ b/apps/demo/src/lib/mdsvex/md/MdUl.svelte
@@ -0,0 +1,3 @@
+<ul class="not-prose my-4 list-disc space-y-2 pl-6 marker:text-primary">
+	<slot />
+</ul>
diff --git a/apps/demo/src/routes/+page.svelte b/apps/demo/src/routes/+page.svelte
index e06dd54..ecdaff0 100644
--- a/apps/demo/src/routes/+page.svelte
+++ b/apps/demo/src/routes/+page.svelte
@@ -20,12 +20,18 @@
 			>
 			<span>enhanced-video-sveltekit</span>
 		</div>
-		<a
-			class="font-mono text-[12.5px] text-muted-foreground hover:text-foreground"
-			href="https://github.com/voadk/enhanced-video-sveltekit"
-			target="_blank"
-			rel="noopener">GitHub ↗</a
-		>
+		<div class="flex items-center gap-4">
+			<a
+				class="font-mono text-[12.5px] text-muted-foreground hover:text-foreground"
+				href="/docs">Docs</a
+			>
+			<a
+				class="font-mono text-[12.5px] text-muted-foreground hover:text-foreground"
+				href="https://github.com/voadk/enhanced-video-sveltekit"
+				target="_blank"
+				rel="noopener">GitHub ↗</a
+			>
+		</div>
 	</header>
 
 	<section class="pt-[88px] pb-16 max-[720px]:pt-14 max-[720px]:pb-10">
diff --git a/apps/demo/src/routes/docs/+layout.svelte b/apps/demo/src/routes/docs/+layout.svelte
new file mode 100644
index 0000000..f0eab65
--- /dev/null
+++ b/apps/demo/src/routes/docs/+layout.svelte
@@ -0,0 +1,44 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	let { children }: { children: Snippet } = $props();
+</script>
+
+<div class="relative min-h-dvh bg-background">
+	<div
+		class="pointer-events-none absolute inset-x-0 top-0 h-[420px] bg-[radial-gradient(ellipse_80%_60%_at_50%_-10%,oklch(0.55_0.2_264_/_0.14),transparent)] dark:bg-[radial-gradient(ellipse_80%_60%_at_50%_-10%,oklch(0.45_0.18_264_/_0.22),transparent)]"
+		aria-hidden="true"
+	></div>
+	<header
+		class="sticky top-0 z-40 border-b border-border/70 bg-background/75 backdrop-blur-xl supports-[backdrop-filter]:bg-background/60"
+	>
+		<div class="mx-auto flex h-14 max-w-5xl items-center justify-between gap-4 px-5 sm:px-8">
+			<a
+				href="/"
+				class="flex items-center gap-2 font-mono text-[13px] text-muted-foreground transition-colors hover:text-foreground"
+			>
+				<span
+					class="grid h-7 w-7 place-items-center rounded-lg bg-foreground text-[11px] font-semibold text-background"
+					>▶</span
+				>
+				<span class="hidden sm:inline">enhanced-video-sveltekit</span>
+				<span class="sm:hidden">evsk</span>
+			</a>
+			<nav class="flex items-center gap-1 text-sm">
+				<a
+					href="/"
+					class="rounded-full px-3 py-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+					>Demo</a
+				>
+				<a
+					href="/docs"
+					class="rounded-full bg-muted px-3 py-1.5 font-medium text-foreground">Docs</a
+				>
+			</nav>
+		</div>
+	</header>
+
+	<main class="relative mx-auto max-w-5xl px-5 py-10 sm:px-8 sm:py-14">
+		{@render children()}
+	</main>
+</div>
diff --git a/apps/demo/src/routes/docs/+page.svx b/apps/demo/src/routes/docs/+page.svx
new file mode 100644
index 0000000..ef274d5
--- /dev/null
+++ b/apps/demo/src/routes/docs/+page.svx
@@ -0,0 +1,187 @@
+---
+title: enhanced-video-sveltekit
+description: Build-time video pipeline for SvelteKit — multi-format transcodes, auto poster, lazy loading, and a single custom element in your markup.
+updated: '2026-05-16'
+---
+
+<script lang="ts">
+	import Callout from '$lib/mdsvex/Callout.svelte';
+	import DocsInstallSwitcher from '$lib/docs/DocsInstallSwitcher.svelte';
+	import DocsVideoFeature from '$lib/docs/DocsVideoFeature.svelte';
+</script>
+
+<svelte:head>
+	<title>{title} — documentation</title>
+	<meta name="description" content={description} />
+</svelte:head>
+
+## Overview
+
+**enhanced-video-sveltekit** is a pair of Vite plugins (markup transform + virtual module loader) that turn a single custom element in your Svelte files into **encoded video variants**, an **auto-extracted poster** (`jpg` plus optional `webp` / `avif`), and a small **runtime component** that handles lazy loading, optional click-to-play, autoplay discipline, and poster fade tied to real playback.
+
+You write a static tag with a **string literal** `src`; the build probes the file with ffprobe, runs ffmpeg for each selected format and resolution, deduplicates work via a **content-hashed disk cache**, and emits optimized assets. The browser receives `<picture>` for the poster and ordered `<source>` elements so it picks the first format it can play.
+
+<Callout title="npm name" tone="info">
+
+The package on npm is **`enhanced-video-sveltekit`**. Internal names (`?enhanced-video`, `/@enhanced-video/`, cache folder `enhanced-video`) stay short on purpose.
+
+</Callout>
+
+## Requirements
+
+| Requirement | Notes |
+| --- | --- |
+| **Node** | ≥ 18 |
+| **Svelte** | ^5 |
+| **Vite** | ^6.3 or ≥ 7 |
+| **@sveltejs/vite-plugin-svelte** | ^6 or ^7 |
+| **ffmpeg / ffprobe** | On `PATH` at build time, or pass `advanced.ffmpegPath` / `ffprobePath`, or install `ffmpeg-ffprobe-static` |
+
+<Callout title="ffmpeg" tone="warning">
+
+Encoding runs **during dev** (background + HMR) and **synchronously on production build**. Missing ffmpeg or a failed encode **fails the build**. Install a build that includes **libx264**, **libx265** (HEVC), **libvpx-vp9**, and **libsvtav1** (AV1) if you enable those formats.
+
+</Callout>
+
+## Install
+
+<DocsInstallSwitcher />
+
+```bash
+# optional: vendored binaries so CI machines do not need system ffmpeg
+pnpm add -D ffmpeg-ffprobe-static
+```
+
+## Vite setup
+
+Add **`enhancedVideos()`** from `enhanced-video-sveltekit` **before** the SvelteKit (or `vite-plugin-svelte`) plugin so the markup transform runs ahead of compilation. If you use Tailwind’s Vite plugin, keep the order shown in this demo:
+
+```ts
+import tailwindcss from '@tailwindcss/vite';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { enhancedVideos } from 'enhanced-video-sveltekit';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+	plugins: [tailwindcss(), enhancedVideos({ resolutions: [360] }), sveltekit()]
+});
+```
+
+This demo passes **`resolutions: [360]`** so cold encodes stay quick; the default ladder is **`[1080, 720, 480]`** (variants taller than the source are skipped).
+
+## Authoring in Svelte
+
+Use the custom element in any **`.svelte`** file (not in raw `.svx` / markdown — put the tag in a `.svelte` wrapper if you author MDsveX). Standard **`<video>`** attributes pass through (`autoplay`, `muted`, `loop`, `controls`, `playsinline`, `class`, `style`, `preload`, ARIA, events, bindings). A user-supplied **`poster`** attribute is ignored; the pipeline always generates one.
+
+<Callout title="Static `src` only" tone="warning">
+
+`src` **must be a string literal**. Dynamic `src={variable}` is rejected with a clear error — the transform has to resolve the file at build time.
+
+</Callout>
+
+Minimal example (angle brackets escaped here so this docs file can live next to the same transform):
+
+```svelte
+&lt;enhanced:video src="./hero.mp4" autoplay muted loop playsinline />
+```
+
+### Runtime props (beyond `<video>`)
+
+These are handled by the generated **`EnhancedVideo`** wrapper (see `enhanced-video-sveltekit/runtime`):
+
+| Prop | Default | Purpose |
+| --- | --- | --- |
+| `loading` | `lazy` | **`lazy`**: gate `<source>` elements behind **IntersectionObserver** until near the viewport. **`eager`**: load immediately. **`click`**: poster + play control until the user starts playback. |
+| `preload` | `metadata` | Forwarded to the underlying `<video>`. |
+| `autoPause` | `true` | Pause when the block scrolls out of view; resume when it returns. |
+| `respectReducedMotion` | `true` | Suppress autoplay when `prefers-reduced-motion: reduce`. |
+| `playLabel` | `Play video` | Accessible label for the click-to-play control when `loading="click"`. |
+
+## What gets encoded
+
+Default **`formats`** are **`['mp4', 'webm']`**: **H.264 + AAC** in MP4 and **VP9 + Opus** in WebM. You can add **`av1`** and **`mp4_hevc`**. The runtime emits `<source type="…">` in **declaration order** — put the format you want modern browsers to try first (for example AV1 before H.264).
+
+| `formats` value | Container | Typical use |
+| --- | --- | --- |
+| `mp4` | MP4 (H.264 + AAC) | Broad compatibility |
+| `webm` | WebM (VP9 + Opus) | Smaller than MP4 for many clips |
+| `mp4_hevc` | MP4 (H.265 + AAC) | Smaller MP4; Safari-oriented tagging |
+| `av1` | WebM (AV1 + Opus) | Best compression where decode exists |
+
+Posters are extracted to **jpg** (always) plus **webp** / **avif** when encoders allow, behind **`<picture>`** for efficient delivery.
+
+## `enhancedVideos(options?)`
+
+| Option | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `formats` | `VideoFormat[]` | `['mp4', 'webm']` | Output codecs to emit |
+| `resolutions` | `number[]` | `[1080, 720, 480]` | Target heights in px |
+| `quality` | `'web' \| 'balanced' \| 'archive'` | `'balanced'` | Preset bundle (CRF, encoder speed, poster quality, audio bitrate) |
+| `cacheDirectory` | `string` | `node_modules/.cache/enhanced-video` | Disk cache root |
+| `maxJobs` | `number` | `max(1, cpus - 1)` | Concurrent ffmpeg jobs |
+| `advanced` | `object` | `{}` | Hardware acceleration, fps cap, binary paths, per-codec overrides, lock TTL |
+
+### `advanced` highlights
+
+| Field | Purpose |
+| --- | --- |
+| `hwAccel` | `'auto'` \| `'videotoolbox'` \| `'nvenc'` \| `'vaapi'` \| `'qsv'` \| `false` — applies to **H.264 / HEVC**; VP9 and AV1 stay software |
+| `fps` | Cap output frame rate |
+| `ffmpegPath` / `ffprobePath` | Override discovery |
+| `overrides` | Per-codec / poster tweaks on top of `quality` (e.g. `h264.crf`, `av1.preset`, `poster.jpg`) |
+| `lockMaxAgeMs` | Stale lock cleanup (default 2h) |
+
+### Quick recipes
+
+```ts
+// faster iteration / CI
+enhancedVideos({ quality: 'web' });
+
+// smaller files, longer encodes
+enhancedVideos({ quality: 'archive' });
+
+// AV1 first, then VP9 WebM, then H.264 MP4
+enhancedVideos({ formats: ['av1', 'webm', 'mp4'] });
+
+// single rung on the resolution ladder
+enhancedVideos({ resolutions: [720] });
+
+// reproducible software-only encodes
+enhancedVideos({ advanced: { hwAccel: false } });
+```
+
+## Programmatic metadata
+
+Import the same pipeline without the custom element:
+
+```ts
+import meta from './clip.mp4?enhanced-video';
+// EnhancedVideoMetadata: width, height, duration, poster { jpg, webp?, avif? }, sources[]
+```
+
+Use this when you want to build your own `<video>` markup or pass data elsewhere.
+
+## Dev vs production
+
+- **Dev:** first load can kick off background encodes; the app may briefly use placeholders while middleware serves assets with **HTTP range** support. Finished jobs **invalidate** modules so HMR picks up new URLs.
+- **Build:** all variants for all discovered sources are encoded **before** the build finishes; failures fail the build.
+
+## Cache
+
+Artifacts live under **`node_modules/.cache/enhanced-video/`** (or your `cacheDirectory`), in **one subdirectory per content hash**. The hash folds in **source bytes**, **encoder args**, **resolved quality profile**, **package version**, and **ffmpeg version banner** — change any of those and you get a new folder. There is **no automatic pruning**; delete the cache directory to reclaim space.
+
+## See it running
+
+The clip below uses the real tag inside a small **`.svelte`** helper (so this MDsveX page never contains the raw substring that would trigger an early parse):
+
+<DocsVideoFeature />
+
+## Limitations
+
+- No **HLS / DASH** adaptive streaming — static `<source>` list only.
+- No **subtitle / caption** pipeline.
+- **`src`** must remain a compile-time string literal.
+
+---
+
+**Repository:** [github.com/voadk/enhanced-video-sveltekit](https://github.com/voadk/enhanced-video-sveltekit) · **License:** MIT
diff --git a/apps/demo/svelte.config.js b/apps/demo/svelte.config.js
index 0e26572..ab1b4b6 100644
--- a/apps/demo/svelte.config.js
+++ b/apps/demo/svelte.config.js
@@ -1,8 +1,34 @@
 import adapter from '@sveltejs/adapter-node';
 import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+import { mdsvex } from 'mdsvex';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import remarkGfm from 'remark-gfm';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** @type {import('mdsvex').MdsvexOptions} */
+const mdsvex_options = {
+	extensions: ['.svx'],
+	layout: {
+		_: join(__dirname, 'src/lib/mdsvex/MdsvexArticleLayout.svelte')
+	},
+	remarkPlugins: [remarkGfm],
+	smartypants: {
+		dashes: 'oldschool'
+	},
+	highlight: {
+		alias: {
+			ts: 'typescript',
+			js: 'javascript'
+		}
+	}
+};
+
+/** @type {import('@sveltejs/kit').Config} */
 const config = {
-	preprocess: vitePreprocess(),
+	extensions: ['.svelte', '.svx'],
+	preprocess: [vitePreprocess(), mdsvex(mdsvex_options)],
 	kit: {
 		adapter: adapter()
 	}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a70b6cb..7000655 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -62,6 +62,15 @@ importers:
       enhanced-video-sveltekit:
         specifier: workspace:*
         version: link:../../packages/enhanced-video
+      mdsvex:
+        specifier: ^0.12.7
+        version: 0.12.7(svelte@5.55.5)
+      prism-themes:
+        specifier: ^1.9.0
+        version: 1.9.0
+      remark-gfm:
+        specifier: ^4.0.1
+        version: 4.0.1
       shadcn-svelte:
         specifier: ^1.2.7
         version: 1.2.7(svelte@5.55.5)
@@ -905,9 +914,18 @@ packages:
   '@types/cookie@0.6.0':
     resolution: {integrity: sha512-4Kh9a6B2bQciAhf7FSuMRRkUWecJgJu9nPnx3yzpsfXX/c50REIqpHY4C82bXP90qrLtXtkDxTZosYO3UpOwlA==}
 
+  '@types/debug@4.1.13':
+    resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==}
+
   '@types/estree@1.0.8':
     resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
 
+  '@types/mdast@4.0.4':
+    resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==}
+
+  '@types/ms@2.1.0':
+    resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==}
+
   '@types/node@20.19.39':
     resolution: {integrity: sha512-orrrD74MBUyK8jOAD/r0+lfa1I2MO6I+vAkmAWzMYbCcgrN4lCrmK52gRFQq/JRxfYPfonkr4b0jcY7Olqdqbw==}
 
@@ -917,6 +935,12 @@ packages:
   '@types/trusted-types@2.0.7':
     resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==}
 
+  '@types/unist@2.0.11':
+    resolution: {integrity: sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==}
+
+  '@types/unist@3.0.3':
+    resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
+
   acorn@8.16.0:
     resolution: {integrity: sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==}
     engines: {node: '>=0.4.0'}
@@ -947,6 +971,9 @@ packages:
     resolution: {integrity: sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ==}
     engines: {node: '>= 0.4'}
 
+  bail@2.0.2:
+    resolution: {integrity: sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==}
+
   bits-ui@2.18.1:
     resolution: {integrity: sha512-KkemzKFH4T3gt3H+P86JcnAWExjByv/6vlwjm/BoCwTPHu03yiCdxbghdJLvFReQTe0acCAiRcKfmixxD6XvlA==}
     engines: {node: '>=20'}
@@ -958,6 +985,12 @@ packages:
     resolution: {integrity: sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==}
     engines: {node: '>=6'}
 
+  ccount@2.0.1:
+    resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==}
+
+  character-entities@2.0.2:
+    resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==}
+
   chokidar@4.0.3:
     resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
     engines: {node: '>= 14.16.0'}
@@ -1026,6 +1059,18 @@ packages:
     engines: {node: '>=4'}
     hasBin: true
 
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  decode-named-character-reference@1.3.0:
+    resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==}
+
   deepmerge@4.3.1:
     resolution: {integrity: sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A==}
     engines: {node: '>=0.10.0'}
@@ -1041,6 +1086,9 @@ packages:
   devalue@5.8.0:
     resolution: {integrity: sha512-2zA9pFEsnp7vWBZbXF5JAgAq0fsUIt/1XPbRiAmRV3lp/2C3upzH+sADiyy66aFCihoLEsrQHxNM5w1gIDfsBg==}
 
+  devlop@1.1.0:
+    resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==}
+
   dot-prop@5.3.0:
     resolution: {integrity: sha512-QM8q3zDe58hqUqjraQOmzZ1LIH9SWQJTlEKCH4kJ2oQvLZk7RbQXvtDM2XEq3fwkV9CCvvH4LA0AV+ogFsBM2Q==}
     engines: {node: '>=8'}
@@ -1075,6 +1123,10 @@ packages:
     resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
     engines: {node: '>=6'}
 
+  escape-string-regexp@5.0.0:
+    resolution: {integrity: sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==}
+    engines: {node: '>=12'}
+
   esm-env@1.2.2:
     resolution: {integrity: sha512-Epxrv+Nr/CaL4ZcFGPJIYLWFom+YeV1DqMLHJoEd9SYRxNbaFruBwfEX/kkHUJf55j2+TUbmDcmuilbP1TmXHA==}
 
@@ -1089,6 +1141,9 @@ packages:
   estree-walker@2.0.2:
     resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==}
 
+  extend@3.0.2:
+    resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==}
+
   fast-deep-equal@3.1.3:
     resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
 
@@ -1284,6 +1339,9 @@ packages:
   locate-character@3.0.0:
     resolution: {integrity: sha512-SW13ws7BjaeJ6p7Q6CO2nchbYEc3X3J6WrmTTDto7yMPqVSZTUyY5Tjbid+Ab8gLnATtygYtiDIJGQRRn2ZOiA==}
 
+  longest-streak@3.1.0:
+    resolution: {integrity: sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==}
+
   lz-string@1.5.0:
     resolution: {integrity: sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==}
     hasBin: true
@@ -1291,10 +1349,135 @@ packages:
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
+  markdown-table@3.0.4:
+    resolution: {integrity: sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==}
+
+  mdast-util-find-and-replace@3.0.2:
+    resolution: {integrity: sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg==}
+
+  mdast-util-from-markdown@2.0.3:
+    resolution: {integrity: sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q==}
+
+  mdast-util-gfm-autolink-literal@2.0.1:
+    resolution: {integrity: sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==}
+
+  mdast-util-gfm-footnote@2.1.0:
+    resolution: {integrity: sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==}
+
+  mdast-util-gfm-strikethrough@2.0.0:
+    resolution: {integrity: sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg==}
+
+  mdast-util-gfm-table@2.0.0:
+    resolution: {integrity: sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==}
+
+  mdast-util-gfm-task-list-item@2.0.0:
+    resolution: {integrity: sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==}
+
+  mdast-util-gfm@3.1.0:
+    resolution: {integrity: sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==}
+
+  mdast-util-phrasing@4.1.0:
+    resolution: {integrity: sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==}
+
+  mdast-util-to-markdown@2.1.2:
+    resolution: {integrity: sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==}
+
+  mdast-util-to-string@4.0.0:
+    resolution: {integrity: sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==}
+
+  mdsvex@0.12.7:
+    resolution: {integrity: sha512-gx4bReLCUvq+MPErHXYeyX+TEq1hsS2KfiZtEOMNTcbibSouFy8AHc5h04KbGCl+g5tLuo4/lbgRVYRnc7bJZw==}
+    peerDependencies:
+      svelte: ^3.56.0 || ^4.0.0 || ^5.0.0-next.120
+
   meow@13.2.0:
     resolution: {integrity: sha512-pxQJQzB6djGPXh08dacEloMFopsOqGVRKFPYvPOt9XDZ1HasbgDZA74CJGreSU4G3Ak7EFJGoiH2auq+yXISgA==}
     engines: {node: '>=18'}
 
+  micromark-core-commonmark@2.0.3:
+    resolution: {integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==}
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    resolution: {integrity: sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==}
+
+  micromark-extension-gfm-footnote@2.1.0:
+    resolution: {integrity: sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==}
+
+  micromark-extension-gfm-strikethrough@2.1.0:
+    resolution: {integrity: sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==}
+
+  micromark-extension-gfm-table@2.1.1:
+    resolution: {integrity: sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==}
+
+  micromark-extension-gfm-tagfilter@2.0.0:
+    resolution: {integrity: sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==}
+
+  micromark-extension-gfm-task-list-item@2.1.0:
+    resolution: {integrity: sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==}
+
+  micromark-extension-gfm@3.0.0:
+    resolution: {integrity: sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==}
+
+  micromark-factory-destination@2.0.1:
+    resolution: {integrity: sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==}
+
+  micromark-factory-label@2.0.1:
+    resolution: {integrity: sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==}
+
+  micromark-factory-space@2.0.1:
+    resolution: {integrity: sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==}
+
+  micromark-factory-title@2.0.1:
+    resolution: {integrity: sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==}
+
+  micromark-factory-whitespace@2.0.1:
+    resolution: {integrity: sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==}
+
+  micromark-util-character@2.1.1:
+    resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==}
+
+  micromark-util-chunked@2.0.1:
+    resolution: {integrity: sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==}
+
+  micromark-util-classify-character@2.0.1:
+    resolution: {integrity: sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==}
+
+  micromark-util-combine-extensions@2.0.1:
+    resolution: {integrity: sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==}
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    resolution: {integrity: sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==}
+
+  micromark-util-decode-string@2.0.1:
+    resolution: {integrity: sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==}
+
+  micromark-util-encode@2.0.1:
+    resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==}
+
+  micromark-util-html-tag-name@2.0.1:
+    resolution: {integrity: sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==}
+
+  micromark-util-normalize-identifier@2.0.1:
+    resolution: {integrity: sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==}
+
+  micromark-util-resolve-all@2.0.1:
+    resolution: {integrity: sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==}
+
+  micromark-util-sanitize-uri@2.0.1:
+    resolution: {integrity: sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==}
+
+  micromark-util-subtokenize@2.1.0:
+    resolution: {integrity: sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==}
+
+  micromark-util-symbol@2.0.1:
+    resolution: {integrity: sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==}
+
+  micromark-util-types@2.0.2:
+    resolution: {integrity: sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==}
+
+  micromark@4.0.2:
+    resolution: {integrity: sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==}
+
   mini-svg-data-uri@1.4.4:
     resolution: {integrity: sha512-r9deDe9p5FJUPZAk3A59wGH7Ii9YrjjWw0jmw/liSbHl2CHiyXj6FcDXDu2K3TjVAXqiJdaw3xxwlZZr9E6nHg==}
     hasBin: true
@@ -1310,6 +1493,9 @@ packages:
     resolution: {integrity: sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ==}
     engines: {node: '>=10'}
 
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
   nanoid@3.3.12:
     resolution: {integrity: sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
@@ -1351,10 +1537,29 @@ packages:
     resolution: {integrity: sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==}
     engines: {node: ^10 || ^12 || >=14}
 
+  prism-svelte@0.4.7:
+    resolution: {integrity: sha512-yABh19CYbM24V7aS7TuPYRNMqthxwbvx6FF/Rw920YbyBWO3tnyPIqRMgHuSVsLmuHkkBS1Akyof463FVdkeDQ==}
+
+  prism-themes@1.9.0:
+    resolution: {integrity: sha512-tX2AYsehKDw1EORwBps+WhBFKc2kxfoFpQAjxBndbZKr4fRmMkv47XN0BghC/K1qwodB1otbe4oF23vUTFDokw==}
+
+  prismjs@1.30.0:
+    resolution: {integrity: sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw==}
+    engines: {node: '>=6'}
+
   readdirp@4.1.2:
     resolution: {integrity: sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==}
     engines: {node: '>= 14.18.0'}
 
+  remark-gfm@4.0.1:
+    resolution: {integrity: sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==}
+
+  remark-parse@11.0.0:
+    resolution: {integrity: sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==}
+
+  remark-stringify@11.0.0:
+    resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==}
+
   require-directory@2.1.1:
     resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
     engines: {node: '>=0.10.0'}
@@ -1493,6 +1698,9 @@ packages:
     resolution: {integrity: sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ==}
     engines: {node: '>=6'}
 
+  trough@2.2.0:
+    resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==}
+
   tslib@2.8.1:
     resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
 
@@ -1507,9 +1715,45 @@ packages:
   undici-types@6.21.0:
     resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
 
+  unified@11.0.5:
+    resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==}
+
+  unist-util-is@4.1.0:
+    resolution: {integrity: sha512-ZOQSsnce92GrxSqlnEEseX0gi7GH9zTJZ0p9dtu87WRb/37mMPO2Ilx1s/t9vBHrFhbgweUwb+t7cIn5dxPhZg==}
+
+  unist-util-is@6.0.1:
+    resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==}
+
+  unist-util-stringify-position@2.0.3:
+    resolution: {integrity: sha512-3faScn5I+hy9VleOq/qNbAd6pAx7iH5jYBMS9I1HgQVijz/4mv5Bvw5iw1sC/90CODiKo81G/ps8AJrISn687g==}
+
+  unist-util-stringify-position@4.0.0:
+    resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==}
+
+  unist-util-visit-parents@3.1.1:
+    resolution: {integrity: sha512-1KROIZWo6bcMrZEwiH2UrXDyalAa0uqzWCxCJj6lPOvTve2WkfgCytoDTPaMnodXh1WrXOq0haVYHj99ynJlsg==}
+
+  unist-util-visit-parents@6.0.2:
+    resolution: {integrity: sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==}
+
+  unist-util-visit@2.0.3:
+    resolution: {integrity: sha512-iJ4/RczbJMkD0712mGktuGpm/U4By4FfDonL7N/9tATGIF4imikjOuagyMY53tnZq3NP6BcmlrHhEKAfGWjh7Q==}
+
+  unist-util-visit@5.1.0:
+    resolution: {integrity: sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==}
+
   util-deprecate@1.0.2:
     resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==}
 
+  vfile-message@2.0.4:
+    resolution: {integrity: sha512-DjssxRGkMvifUOJre00juHoP9DPWuzjxKuMDrhNbk2TdaYYBNMStsNhEOt3idrtI12VQYM/1+iM0KOzXi4pxwQ==}
+
+  vfile-message@4.0.3:
+    resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==}
+
+  vfile@6.0.3:
+    resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==}
+
   vite@7.3.2:
     resolution: {integrity: sha512-Bby3NOsna2jsjfLVOHKes8sGwgl4TT0E6vvpYgnAYDIF/tie7MRaFthmKuHx1NSXjiTueXH3do80FMQgvEktRg==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -1581,6 +1825,9 @@ packages:
   zimmerframe@1.1.4:
     resolution: {integrity: sha512-B58NGBEoc8Y9MWWCQGl/gq9xBCe4IiKM0a2x7GZdQKOW5Exr8S1W24J6OgM1njK8xCRGvAJIL/MxXHf6SkmQKQ==}
 
+  zwitch@2.0.4:
+    resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==}
+
 snapshots:
 
   '@babel/code-frame@7.29.0':
@@ -2184,8 +2431,18 @@ snapshots:
 
   '@types/cookie@0.6.0': {}
 
+  '@types/debug@4.1.13':
+    dependencies:
+      '@types/ms': 2.1.0
+
   '@types/estree@1.0.8': {}
 
+  '@types/mdast@4.0.4':
+    dependencies:
+      '@types/unist': 2.0.11
+
+  '@types/ms@2.1.0': {}
+
   '@types/node@20.19.39':
     dependencies:
       undici-types: 6.21.0
@@ -2194,6 +2451,10 @@ snapshots:
 
   '@types/trusted-types@2.0.7': {}
 
+  '@types/unist@2.0.11': {}
+
+  '@types/unist@3.0.3': {}
+
   acorn@8.16.0: {}
 
   ajv@8.20.0:
@@ -2217,6 +2478,8 @@ snapshots:
 
   axobject-query@4.1.0: {}
 
+  bail@2.0.2: {}
+
   bits-ui@2.18.1(@internationalized/date@3.12.1)(@sveltejs/kit@2.59.1(@sveltejs/vite-plugin-svelte@6.2.4(svelte@5.55.5)(vite@7.3.2(@types/node@20.19.39)(jiti@2.7.0)(lightningcss@1.32.0)))(svelte@5.55.5)(typescript@5.9.3)(vite@7.3.2(@types/node@20.19.39)(jiti@2.7.0)(lightningcss@1.32.0)))(svelte@5.55.5):
     dependencies:
       '@floating-ui/core': 1.7.5
@@ -2232,6 +2495,10 @@ snapshots:
 
   callsites@3.1.0: {}
 
+  ccount@2.0.1: {}
+
+  character-entities@2.0.2: {}
+
   chokidar@4.0.3:
     dependencies:
       readdirp: 4.1.2
@@ -2292,6 +2559,14 @@ snapshots:
 
   cssesc@3.0.0: {}
 
+  debug@4.4.3:
+    dependencies:
+      ms: 2.1.3
+
+  decode-named-character-reference@1.3.0:
+    dependencies:
+      character-entities: 2.0.2
+
   deepmerge@4.3.1: {}
 
   dequal@2.0.3: {}
@@ -2300,6 +2575,10 @@ snapshots:
 
   devalue@5.8.0: {}
 
+  devlop@1.1.0:
+    dependencies:
+      dequal: 2.0.3
+
   dot-prop@5.3.0:
     dependencies:
       is-obj: 2.0.0
@@ -2352,6 +2631,8 @@ snapshots:
 
   escalade@3.2.0: {}
 
+  escape-string-regexp@5.0.0: {}
+
   esm-env@1.2.2: {}
 
   esrap@2.2.6:
@@ -2360,6 +2641,8 @@ snapshots:
 
   estree-walker@2.0.2: {}
 
+  extend@3.0.2: {}
+
   fast-deep-equal@3.1.3: {}
 
   fast-uri@3.1.2: {}
@@ -2497,14 +2780,321 @@ snapshots:
 
   locate-character@3.0.0: {}
 
+  longest-streak@3.1.0: {}
+
   lz-string@1.5.0: {}
 
   magic-string@0.30.21:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
 
+  markdown-table@3.0.4: {}
+
+  mdast-util-find-and-replace@3.0.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      escape-string-regexp: 5.0.0
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
+  mdast-util-from-markdown@2.0.3:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      mdast-util-to-string: 4.0.0
+      micromark: 4.0.2
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-decode-string: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-stringify-position: 4.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-autolink-literal@2.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      ccount: 2.0.1
+      devlop: 1.1.0
+      mdast-util-find-and-replace: 3.0.2
+      micromark-util-character: 2.1.1
+
+  mdast-util-gfm-footnote@2.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      micromark-util-normalize-identifier: 2.0.1
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-strikethrough@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-table@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      markdown-table: 3.0.4
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-task-list-item@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm@3.1.0:
+    dependencies:
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-gfm-autolink-literal: 2.0.1
+      mdast-util-gfm-footnote: 2.1.0
+      mdast-util-gfm-strikethrough: 2.0.0
+      mdast-util-gfm-table: 2.0.0
+      mdast-util-gfm-task-list-item: 2.0.0
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-phrasing@4.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      unist-util-is: 6.0.1
+
+  mdast-util-to-markdown@2.1.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      longest-streak: 3.1.0
+      mdast-util-phrasing: 4.1.0
+      mdast-util-to-string: 4.0.0
+      micromark-util-classify-character: 2.0.1
+      micromark-util-decode-string: 2.0.1
+      unist-util-visit: 5.1.0
+      zwitch: 2.0.4
+
+  mdast-util-to-string@4.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+
+  mdsvex@0.12.7(svelte@5.55.5):
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 2.0.11
+      prism-svelte: 0.4.7
+      prismjs: 1.30.0
+      svelte: 5.55.5
+      unist-util-visit: 2.0.3
+      vfile-message: 2.0.4
+
   meow@13.2.0: {}
 
+  micromark-core-commonmark@2.0.3:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-factory-destination: 2.0.1
+      micromark-factory-label: 2.0.1
+      micromark-factory-space: 2.0.1
+      micromark-factory-title: 2.0.1
+      micromark-factory-whitespace: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-html-tag-name: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-footnote@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-strikethrough@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-table@2.1.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-tagfilter@2.0.0:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-task-list-item@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm@3.0.0:
+    dependencies:
+      micromark-extension-gfm-autolink-literal: 2.1.0
+      micromark-extension-gfm-footnote: 2.1.0
+      micromark-extension-gfm-strikethrough: 2.1.0
+      micromark-extension-gfm-table: 2.1.1
+      micromark-extension-gfm-tagfilter: 2.0.0
+      micromark-extension-gfm-task-list-item: 2.1.0
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-destination@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-label@2.0.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-space@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-title@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-whitespace@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-character@2.1.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-chunked@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-classify-character@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-combine-extensions@2.0.1:
+    dependencies:
+      micromark-util-chunked: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-decode-string@2.0.1:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      micromark-util-character: 2.1.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-encode@2.0.1: {}
+
+  micromark-util-html-tag-name@2.0.1: {}
+
+  micromark-util-normalize-identifier@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-resolve-all@2.0.1:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-util-sanitize-uri@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-encode: 2.0.1
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-subtokenize@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-symbol@2.0.1: {}
+
+  micromark-util-types@2.0.2: {}
+
+  micromark@4.0.2:
+    dependencies:
+      '@types/debug': 4.1.13
+      debug: 4.4.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-encode: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
   mini-svg-data-uri@1.4.4: {}
 
   minimist@1.2.8: {}
@@ -2513,6 +3103,8 @@ snapshots:
 
   mrmime@2.0.1: {}
 
+  ms@2.1.3: {}
+
   nanoid@3.3.12: {}
 
   node-fetch-native@1.6.7: {}
@@ -2551,8 +3143,40 @@ snapshots:
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
+  prism-svelte@0.4.7: {}
+
+  prism-themes@1.9.0: {}
+
+  prismjs@1.30.0: {}
+
   readdirp@4.1.2: {}
 
+  remark-gfm@4.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-gfm: 3.1.0
+      micromark-extension-gfm: 3.0.0
+      remark-parse: 11.0.0
+      remark-stringify: 11.0.0
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-parse@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      micromark-util-types: 2.0.2
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-stringify@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-to-markdown: 2.1.2
+      unified: 11.0.5
+
   require-directory@2.1.1: {}
 
   require-from-string@2.0.2: {}
@@ -2748,6 +3372,8 @@ snapshots:
 
   totalist@3.0.1: {}
 
+  trough@2.2.0: {}
+
   tslib@2.8.1: {}
 
   tw-animate-css@1.4.0: {}
@@ -2756,8 +3382,69 @@ snapshots:
 
   undici-types@6.21.0: {}
 
+  unified@11.0.5:
+    dependencies:
+      '@types/unist': 3.0.3
+      bail: 2.0.2
+      devlop: 1.1.0
+      extend: 3.0.2
+      is-plain-obj: 4.1.0
+      trough: 2.2.0
+      vfile: 6.0.3
+
+  unist-util-is@4.1.0: {}
+
+  unist-util-is@6.0.1:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-stringify-position@2.0.3:
+    dependencies:
+      '@types/unist': 2.0.11
+
+  unist-util-stringify-position@4.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-visit-parents@3.1.1:
+    dependencies:
+      '@types/unist': 2.0.11
+      unist-util-is: 4.1.0
+
+  unist-util-visit-parents@6.0.2:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+
+  unist-util-visit@2.0.3:
+    dependencies:
+      '@types/unist': 2.0.11
+      unist-util-is: 4.1.0
+      unist-util-visit-parents: 3.1.1
+
+  unist-util-visit@5.1.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
   util-deprecate@1.0.2: {}
 
+  vfile-message@2.0.4:
+    dependencies:
+      '@types/unist': 2.0.11
+      unist-util-stringify-position: 2.0.3
+
+  vfile-message@4.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-stringify-position: 4.0.0
+
+  vfile@6.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      vfile-message: 4.0.3
+
   vite@7.3.2(@types/node@20.19.39)(jiti@2.7.0)(lightningcss@1.32.0):
     dependencies:
       esbuild: 0.27.7
@@ -2799,3 +3486,5 @@ snapshots:
   yocto-queue@1.2.2: {}
 
   zimmerframe@1.1.4: {}
+
+  zwitch@2.0.4: {}

From d3901f0c6e09628f2fc5167f4571a53f10f6b4ce Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 17 May 2026 12:15:15 +0000
Subject: [PATCH 2/2] docs(demo): expand /docs with architecture, formats, and
 setup detail

---
 apps/demo/src/routes/docs/+page.svx | 186 +++++++++++++++++++---------
 1 file changed, 125 insertions(+), 61 deletions(-)

diff --git a/apps/demo/src/routes/docs/+page.svx b/apps/demo/src/routes/docs/+page.svx
index ef274d5..56e0f22 100644
--- a/apps/demo/src/routes/docs/+page.svx
+++ b/apps/demo/src/routes/docs/+page.svx
@@ -17,44 +17,67 @@ updated: '2026-05-16'
 
 ## Overview
 
-**enhanced-video-sveltekit** is a pair of Vite plugins (markup transform + virtual module loader) that turn a single custom element in your Svelte files into **encoded video variants**, an **auto-extracted poster** (`jpg` plus optional `webp` / `avif`), and a small **runtime component** that handles lazy loading, optional click-to-play, autoplay discipline, and poster fade tied to real playback.
+**enhanced-video-sveltekit** ships **`enhancedVideos()`** — two coordinated **Vite** plugins:
 
-You write a static tag with a **string literal** `src`; the build probes the file with ffprobe, runs ffmpeg for each selected format and resolution, deduplicates work via a **content-hashed disk cache**, and emits optimized assets. The browser receives `<picture>` for the poster and ordered `<source>` elements so it picks the first format it can play.
+1. **Markup plugin** (`order: 'pre'`) scans `.svelte` sources for the custom **`enhanced:video`** element (same namespace as HTML, so it is written like a normal tag in Svelte). It rewrites markup to the runtime **`EnhancedVideo`** component, wires **`metadata`** from a virtual import, and preserves passthrough **`<video>`** attributes.
+2. **Loader plugin** (`enforce: 'pre'`) implements the **`?enhanced-video`** virtual module: **ffprobe** the source, **ffmpeg** each selected format × resolution, write **content-hashed** artifacts to disk cache, emit URLs. In **dev**, middleware serves bytes with **HTTP range** support; in **build**, assets are emitted like other Vite files.
+
+You keep a **static string** `src` in markup; the build resolves paths, encodes, and hands the browser a **`<picture>`** poster plus ordered **`<source>`** children so playback picks the first decodable stream.
 
 <Callout title="npm name" tone="info">
 
-The package on npm is **`enhanced-video-sveltekit`**. Internal names (`?enhanced-video`, `/@enhanced-video/`, cache folder `enhanced-video`) stay short on purpose.
+The package on npm is **`enhanced-video-sveltekit`**. Internal strings (`?enhanced-video`, `/@enhanced-video/`, cache dir **`enhanced-video`**) stay short on purpose.
 
 </Callout>
 
+## What you get
+
+- **Multi-height ladder** — default targets **1080p, 720p, 480p**; rungs taller than the source are skipped, and rungs within **~10%** height of a kept larger rung are deduplicated.
+- **Multi-codec outputs** — default **`mp4` + `webm`** (H.264 / VP9); optional **AV1** and **HEVC-in-MP4** (`mp4_hevc`).
+- **Auto poster** — extracted frame as **jpg** plus optional **webp** / **avif** behind **`<picture>`** (helps LCP / CLS). User **`poster=`** attrs are dropped by design.
+- **Lazy by default** — **`loading="lazy"`** keeps **`<source>`** out of the DOM until an **IntersectionObserver** says the block is near the viewport, so no fetch until needed.
+- **Playback polish** — poster overlay fades on **real playback** (timeupdate / playing / error + short fallback), optional **auto-pause** when scrolled away, **`prefers-reduced-motion`** respected for autoplay, **`loading="click"`** for explicit play.
+- **Disk cache** — repeat dev / CI runs hit cache; key includes **source bytes**, **args**, **quality profile**, **package version**, **ffmpeg banner**.
+- **Dev UX** — cold encode can show a **placeholder** first; when encodes finish, modules **invalidate** for **HMR**. Terminal **progress** for long jobs (TTY bar, plain lines otherwise).
+- **Types** — re-exported **`EnhancedVideoMetadata`**, **`EnhancedVideosOptions`**, **`VideoFormat`**, etc., from the package entry.
+
 ## Requirements
 
 | Requirement | Notes |
 | --- | --- |
 | **Node** | ≥ 18 |
+| **ffmpeg / ffprobe** | ≥ **6** with **libx264**, **libx265**, **libvpx-vp9**, **libsvtav1** when you use those codecs (Homebrew / Debian / Chocolatey builds usually include them; static npm packages too) |
 | **Svelte** | ^5 |
 | **Vite** | ^6.3 or ≥ 7 |
 | **@sveltejs/vite-plugin-svelte** | ^6 or ^7 |
-| **ffmpeg / ffprobe** | On `PATH` at build time, or pass `advanced.ffmpegPath` / `ffprobePath`, or install `ffmpeg-ffprobe-static` |
 
-<Callout title="ffmpeg" tone="warning">
+<Callout title="Build-time tool" tone="warning">
 
-Encoding runs **during dev** (background + HMR) and **synchronously on production build**. Missing ffmpeg or a failed encode **fails the build**. Install a build that includes **libx264**, **libx265** (HEVC), **libvpx-vp9**, and **libsvtav1** (AV1) if you enable those formats.
+Encoding runs in **dev** (background + HMR) and **synchronously on production build**. Missing binaries or a failed encode **fails the build** — treat ffmpeg like a compiler dependency.
 
 </Callout>
 
+### Binary resolution order
+
+`ffmpeg` / `ffprobe` are resolved in this order (first hit wins):
+
+1. **`advanced.ffmpegPath`** / **`advanced.ffprobePath`**
+2. **`ffmpeg-ffprobe-static`** (if installed)
+3. **`ffmpeg-static`** + **`ffprobe-static`** (if installed)
+4. **`PATH`**
+
 ## Install
 
 <DocsInstallSwitcher />
 
 ```bash
-# optional: vendored binaries so CI machines do not need system ffmpeg
+# optional: vendored binaries so CI agents do not need system ffmpeg
 pnpm add -D ffmpeg-ffprobe-static
 ```
 
 ## Vite setup
 
-Add **`enhancedVideos()`** from `enhanced-video-sveltekit` **before** the SvelteKit (or `vite-plugin-svelte`) plugin so the markup transform runs ahead of compilation. If you use Tailwind’s Vite plugin, keep the order shown in this demo:
+Call **`enhancedVideos()`** **before** **`sveltekit()`** (or **`svelte()`** in a non-Kit Vite + Svelte app) so the markup transform runs **ahead of** `vite-plugin-svelte:compile`. With **Tailwind v4**’s Vite plugin, a typical stack looks like:
 
 ```ts
 import tailwindcss from '@tailwindcss/vite';
@@ -67,120 +90,161 @@ export default defineConfig({
 });
 ```
 
-This demo passes **`resolutions: [360]`** so cold encodes stay quick; the default ladder is **`[1080, 720, 480]`** (variants taller than the source are skipped).
+This demo passes **`resolutions: [360]`** so first-time encodes stay small; defaults are **`[1080, 720, 480]`**.
 
 ## Authoring in Svelte
 
-Use the custom element in any **`.svelte`** file (not in raw `.svx` / markdown — put the tag in a `.svelte` wrapper if you author MDsveX). Standard **`<video>`** attributes pass through (`autoplay`, `muted`, `loop`, `controls`, `playsinline`, `class`, `style`, `preload`, ARIA, events, bindings). A user-supplied **`poster`** attribute is ignored; the pipeline always generates one.
+Author the tag in **`.svelte`** files only (for MDsveX / markdown, import a tiny **`.svelte`** wrapper that contains the tag — raw `.svx` must not include the literal **open tag sequence** or the markup plugin will try to parse markdown as Svelte).
+
+Passthrough works like **`HTMLVideoElement`**: **`autoplay`**, **`muted`**, **`loop`**, **`controls`**, **`playsinline`**, **`class`**, **`style`**, **`preload`**, ARIA, **`data-*`**, events, bindings, etc.
 
 <Callout title="Static `src` only" tone="warning">
 
-`src` **must be a string literal**. Dynamic `src={variable}` is rejected with a clear error — the transform has to resolve the file at build time.
+`src` **must be a string literal** at transform time. Dynamic **`src={expr}`** throws on purpose — the tool has to read the file from disk during the build.
 
 </Callout>
 
-Minimal example (angle brackets escaped here so this docs file can live next to the same transform):
+Minimal markup (escaped here so this docs source stays parse-safe):
 
 ```svelte
 &lt;enhanced:video src="./hero.mp4" autoplay muted loop playsinline />
 ```
 
-### Runtime props (beyond `<video>`)
-
-These are handled by the generated **`EnhancedVideo`** wrapper (see `enhanced-video-sveltekit/runtime`):
+### Runtime props (`enhanced-video-sveltekit/runtime`)
 
 | Prop | Default | Purpose |
 | --- | --- | --- |
-| `loading` | `lazy` | **`lazy`**: gate `<source>` elements behind **IntersectionObserver** until near the viewport. **`eager`**: load immediately. **`click`**: poster + play control until the user starts playback. |
-| `preload` | `metadata` | Forwarded to the underlying `<video>`. |
-| `autoPause` | `true` | Pause when the block scrolls out of view; resume when it returns. |
-| `respectReducedMotion` | `true` | Suppress autoplay when `prefers-reduced-motion: reduce`. |
-| `playLabel` | `Play video` | Accessible label for the click-to-play control when `loading="click"`. |
+| `loading` | `lazy` | **`lazy`**: gate **`<source>`** behind **IntersectionObserver**. **`eager`**: load immediately. **`click`**: poster + button until the user plays. |
+| `preload` | `metadata` | Forwarded to the underlying **`<video>`**. |
+| `autoPause` | `true` | Pause off-screen; resume when visible again. |
+| `respectReducedMotion` | `true` | Skip autoplay when **`prefers-reduced-motion: reduce`**. |
+| `playLabel` | `Play video` | ARIA label for click-to-play (**`loading="click"`**). |
 
-## What gets encoded
+## Output formats
 
-Default **`formats`** are **`['mp4', 'webm']`**: **H.264 + AAC** in MP4 and **VP9 + Opus** in WebM. You can add **`av1`** and **`mp4_hevc`**. The runtime emits `<source type="…">` in **declaration order** — put the format you want modern browsers to try first (for example AV1 before H.264).
+| `formats` key | Video codec | Audio | Container | Notes |
+| --- | --- | --- | --- | --- |
+| `mp4` | H.264 | AAC | MP4 | Widest compatibility |
+| `webm` | VP9 | Opus | WebM | Often smaller than H.264 for web |
+| `mp4_hevc` | H.265 | AAC | MP4 | **`hvc1`** style tagging for Apple-friendly MP4 |
+| `av1` | AV1 | Opus | WebM | Best compression; decode on current Chrome / Firefox / Safari |
 
-| `formats` value | Container | Typical use |
-| --- | --- | --- |
-| `mp4` | MP4 (H.264 + AAC) | Broad compatibility |
-| `webm` | WebM (VP9 + Opus) | Smaller than MP4 for many clips |
-| `mp4_hevc` | MP4 (H.265 + AAC) | Smaller MP4; Safari-oriented tagging |
-| `av1` | WebM (AV1 + Opus) | Best compression where decode exists |
+**`<source type="…">`** order follows your **`formats`** array — put the stream you want modern browsers to **try first** (for example **`av1`** before **`mp4`**).
+
+Posters: **jpg** always; **webp** / **avif** when encoders succeed — wrapped in **`<picture>`**.
 
-Posters are extracted to **jpg** (always) plus **webp** / **avif** when encoders allow, behind **`<picture>`** for efficient delivery.
+## Quality & ladder
+
+**`quality`** picks a preset bundle (CRF-ish targets, encoder speed, audio bitrates, poster quality):
+
+| Value | When to use |
+| --- | --- |
+| **`web`** | Faster CI / local iteration; smaller outputs vs **`balanced`** |
+| **`balanced`** | Default sweet spot |
+| **`archive`** | Slower, higher fidelity, larger files |
+
+**`resolutions`** is a list of **target heights in px**, descending. The loader skips outputs taller than the source and collapses rungs that are **redundant** (within ~**10%** of a larger kept rung).
 
 ## `enhancedVideos(options?)`
 
 | Option | Type | Default | Purpose |
 | --- | --- | --- | --- |
-| `formats` | `VideoFormat[]` | `['mp4', 'webm']` | Output codecs to emit |
-| `resolutions` | `number[]` | `[1080, 720, 480]` | Target heights in px |
-| `quality` | `'web' \| 'balanced' \| 'archive'` | `'balanced'` | Preset bundle (CRF, encoder speed, poster quality, audio bitrate) |
-| `cacheDirectory` | `string` | `node_modules/.cache/enhanced-video` | Disk cache root |
-| `maxJobs` | `number` | `max(1, cpus - 1)` | Concurrent ffmpeg jobs |
-| `advanced` | `object` | `{}` | Hardware acceleration, fps cap, binary paths, per-codec overrides, lock TTL |
+| `formats` | `VideoFormat[]` | `['mp4', 'webm']` | Which codec families to emit |
+| `resolutions` | `number[]` | `[1080, 720, 480]` | Height ladder (see above) |
+| `quality` | `'web' \| 'balanced' \| 'archive'` | `'balanced'` | Preset bundle |
+| `cacheDirectory` | `string` | nearest **`node_modules/.cache/enhanced-video`** | Output cache root |
+| `maxJobs` | `number` | **`max(1, cpus - 1)`** | Parallel ffmpeg cap |
+| `advanced` | `AdvancedOptions` | `{}` | Hardware accel, fps cap, paths, overrides, locks |
 
-### `advanced` highlights
+### `advanced`
 
 | Field | Purpose |
 | --- | --- |
-| `hwAccel` | `'auto'` \| `'videotoolbox'` \| `'nvenc'` \| `'vaapi'` \| `'qsv'` \| `false` — applies to **H.264 / HEVC**; VP9 and AV1 stay software |
-| `fps` | Cap output frame rate |
-| `ffmpegPath` / `ffprobePath` | Override discovery |
-| `overrides` | Per-codec / poster tweaks on top of `quality` (e.g. `h264.crf`, `av1.preset`, `poster.jpg`) |
-| `lockMaxAgeMs` | Stale lock cleanup (default 2h) |
+| `hwAccel` | **`'auto'`** \| **`'videotoolbox'`** \| **`'nvenc'`** \| **`'vaapi'`** \| **`'qsv'`** \| **`false`** — **H.264 / HEVC** only; **VP9 + AV1** stay software |
+| `fps` | **`min(fps, source_fps)`** cap |
+| `ffmpegPath` / `ffprobePath` | Explicit binaries |
+| `lockMaxAgeMs` | Stale lock cleanup (**default 2h**) |
+| `overrides` | Per-codec / poster knobs layered on **`quality`** |
 
-### Quick recipes
+### `QualityOverrides` (TypeScript)
 
 ```ts
-// faster iteration / CI
-enhancedVideos({ quality: 'web' });
+{
+	h264?: { crf?: number; preset?: string };
+	hevc?: { crf?: number; preset?: string };
+	vp9?: { crf?: number; cpuUsed?: number };
+	av1?: { crf?: number; preset?: number };
+	audio?: { mp4Bitrate?: string; webmBitrate?: string };
+	poster?: { jpg?: number; webp?: number; avif?: number };
+}
+```
 
-// smaller files, longer encodes
-enhancedVideos({ quality: 'archive' });
+### Recipe snippets
 
-// AV1 first, then VP9 WebM, then H.264 MP4
+```ts
+enhancedVideos({ quality: 'web' });
+enhancedVideos({ quality: 'archive' });
 enhancedVideos({ formats: ['av1', 'webm', 'mp4'] });
-
-// single rung on the resolution ladder
 enhancedVideos({ resolutions: [720] });
-
-// reproducible software-only encodes
 enhancedVideos({ advanced: { hwAccel: false } });
+
+enhancedVideos({
+	quality: 'balanced',
+	advanced: {
+		overrides: {
+			h264: { crf: 18, preset: 'slow' },
+			poster: { jpg: 95 }
+		}
+	}
+});
 ```
 
 ## Programmatic metadata
 
-Import the same pipeline without the custom element:
+Skip the custom element and import metadata only:
 
 ```ts
 import meta from './clip.mp4?enhanced-video';
-// EnhancedVideoMetadata: width, height, duration, poster { jpg, webp?, avif? }, sources[]
+// EnhancedVideoMetadata — width, height, duration, poster { jpg, webp?, avif? }, sources[]
 ```
 
-Use this when you want to build your own `<video>` markup or pass data elsewhere.
+Useful for custom **`<video>`** markup, CMS previews, or tests.
+
+## Browser notes (default `formats`)
+
+Exact stream picked is **codec + browser** dependent. With **`['mp4','webm']`** you generally see **H.264** and **VP9** candidates; adding **`av1`** / **`mp4_hevc`** changes the matrix.
+
+| Browser | Typical first choice (defaults) |
+| --- | --- |
+| Chrome / Edge | H.264 in MP4, then VP9 WebM if skipped |
+| Firefox | H.264 / VP9 depending on profile |
+| Safari 17+ | H.264; **HEVC** only if you enabled **`mp4_hevc`** |
 
 ## Dev vs production
 
-- **Dev:** first load can kick off background encodes; the app may briefly use placeholders while middleware serves assets with **HTTP range** support. Finished jobs **invalidate** modules so HMR picks up new URLs.
-- **Build:** all variants for all discovered sources are encoded **before** the build finishes; failures fail the build.
+- **Dev** — first request may **encode in the background** while a **placeholder** points at the original asset; when jobs finish, **module invalidation** swaps in final URLs (**HMR**). Range requests supported on generated URLs.
+- **Production** — all referenced sources are **fully encoded before** the build completes; failures surface as **build errors**.
 
 ## Cache
 
-Artifacts live under **`node_modules/.cache/enhanced-video/`** (or your `cacheDirectory`), in **one subdirectory per content hash**. The hash folds in **source bytes**, **encoder args**, **resolved quality profile**, **package version**, and **ffmpeg version banner** — change any of those and you get a new folder. There is **no automatic pruning**; delete the cache directory to reclaim space.
+Outputs live under **`node_modules/.cache/enhanced-video/`** (or **`cacheDirectory`**), one folder per **hash** mixing **source bytes**, **encoder args**, **resolved quality profile**, **package version**, and **ffmpeg version banner**. There is **no automatic pruning** — delete the folder to reclaim disk.
+
+## WebContainers
+
+On **`process.versions.webcontainer`**, **`enhancedVideos()`** returns **no plugins** (StackBlitz-style environments without ffmpeg). Use the docs **locally** or in CI with ffmpeg installed.
 
 ## See it running
 
-The clip below uses the real tag inside a small **`.svelte`** helper (so this MDsveX page never contains the raw substring that would trigger an early parse):
+Live pipeline (real tag lives in **`DocsVideoFeature.svelte`**, not in this `.svx`):
 
 <DocsVideoFeature />
 
 ## Limitations
 
-- No **HLS / DASH** adaptive streaming — static `<source>` list only.
-- No **subtitle / caption** pipeline.
-- **`src`** must remain a compile-time string literal.
+- **No HLS / DASH** — static **`<source>`** list only.
+- **No subtitle / caption** pipeline.
+- **`src`** must stay a **compile-time string literal**.
+- **Cache** is not auto-pruned.
 
 ---