feat(examples): lazy load demo code references

- Allow CodeReferenceV2 samples to load code payloads after hydration
- Add split demo manifest output with virtual demo modules
- Export split manifest types for docs consumers

Author: jaysin586

src/lib/components/CodeReferenceV2.svelte

@@ -36,14 +36,9 @@
     import { AnimatePresence, MotionButton, MotionSpan } from '@humanspeak/svelte-motion'
     import CheckIcon from '@lucide/svelte/icons/check'
     import CopyIcon from '@lucide/svelte/icons/copy'
-    import { onDestroy } from 'svelte'
+    import { onDestroy, onMount } from 'svelte'
 
-    interface CodeSample {
-        /** Stable identifier — surfaces as the small-caps tag on the left of
-         *  the header strip. */
-        id: string
-        /** Display title rendered as the header's `<h3>`. */
-        label: string
+    interface CodeSamplePayload {
         /** The raw code text. Used for the copy button and as the plain-text
          *  fallback when `html` is not provided. */
         code: string
@@ -56,15 +51,51 @@
         html?: { light: string; dark: string }
     }
 
+    interface EagerCodeSample extends CodeSamplePayload {
+        /** Stable identifier — surfaces as the small-caps tag on the left of
+         *  the header strip. */
+        id: string
+        /** Display title rendered as the header's `<h3>`. */
+        label: string
+    }
+
+    interface LazyCodeSample {
+        /** Stable identifier — surfaces as the small-caps tag on the left of
+         *  the header strip. */
+        id: string
+        /** Display title rendered as the header's `<h3>`. */
+        label: string
+        /** Load the raw/highlighted code on demand. Supports both a plain
+         *  payload and an ESM module default export so consumers can pass
+         *  `() => import('virtual:docs-kit/demo/...')` directly. */
+        load: () => Promise<CodeSamplePayload | { default: CodeSamplePayload }>
+        /** Override component-level lazy preloading for this sample. */
+        preload?: 'idle' | false
+    }
+
+    type CodeSample = EagerCodeSample | LazyCodeSample
+    type IdleRuntime = typeof globalThis & {
+        requestIdleCallback?: (callback: () => void) => number
+        cancelIdleCallback?: (id: number) => void
+    }
+
+    function isLazySample(sample: CodeSample): sample is LazyCodeSample {
+        return 'load' in sample
+    }
+
     interface Props {
         samples: CodeSample[]
         /** Columns at desktop width. Default `auto`, which uses the number of
          *  samples up to 3 (so 1 sample = 1 col, 4 samples = still 3 cols
          *  wrapping). Pass an integer to force a specific column count. */
         columns?: number | 'auto'
+        /** Lazy sample preload strategy. `idle` fetches after hydration so
+         *  code drawers are warm without blocking the initial page. Eager
+         *  samples are unaffected. */
+        preload?: 'idle' | false
     }
 
-    const { samples, columns = 'auto' }: Props = $props()
+    const { samples, columns = 'auto', preload = 'idle' }: Props = $props()
 
     const colCount = $derived(
         columns === 'auto' ? Math.min(samples.length, 3) : Math.max(1, columns)
@@ -75,6 +106,11 @@
     // show "copied" independently if the user clicks through them quickly.
     let copiedId = $state<string | null>(null)
     let copyResetTimer: ReturnType<typeof setTimeout> | null = null
+    let loadedById = $state<Record<string, CodeSamplePayload>>({})
+    let loadingById = $state<Record<string, boolean>>({})
+    let errorById = $state<Record<string, boolean>>({})
+    const pendingById = new Map<string, Promise<CodeSamplePayload | null>>()
+    const cancelPreloads: Array<() => void> = []
 
     const showCopyFeedback = (sampleId: string) => {
         copiedId = sampleId
@@ -85,18 +121,88 @@
         }, 1600)
     }
 
+    const getPayload = (sample: CodeSample): CodeSamplePayload | null => {
+        if (!isLazySample(sample)) return sample
+        return loadedById[sample.id] ?? null
+    }
+
+    const unwrapPayload = (
+        payload: CodeSamplePayload | { default: CodeSamplePayload }
+    ): CodeSamplePayload => ('default' in payload ? payload.default : payload)
+
+    const loadSample = async (sample: CodeSample): Promise<CodeSamplePayload | null> => {
+        if (!isLazySample(sample)) return sample
+
+        const cached = loadedById[sample.id]
+        if (cached) return cached
+
+        const pending = pendingById.get(sample.id)
+        if (pending) return pending
+
+        loadingById = { ...loadingById, [sample.id]: true }
+        errorById = { ...errorById, [sample.id]: false }
+
+        const next = sample
+            .load()
+            .then((payload) => {
+                const loaded = unwrapPayload(payload)
+                loadedById = { ...loadedById, [sample.id]: loaded }
+                return loaded
+            })
+            .catch(() => {
+                errorById = { ...errorById, [sample.id]: true }
+                return null
+            })
+            .finally(() => {
+                loadingById = { ...loadingById, [sample.id]: false }
+                pendingById.delete(sample.id)
+            })
+
+        pendingById.set(sample.id, next)
+        return next
+    }
+
+    const scheduleIdlePreload = (sample: LazyCodeSample) => {
+        const runtime = globalThis as IdleRuntime
+
+        const run = () => {
+            void loadSample(sample)
+        }
+
+        if (runtime.requestIdleCallback && runtime.cancelIdleCallback) {
+            const id = runtime.requestIdleCallback(run)
+            cancelPreloads.push(() => runtime.cancelIdleCallback?.(id))
+            return
+        }
+
+        const id = globalThis.setTimeout(run, 250)
+        cancelPreloads.push(() => globalThis.clearTimeout(id))
+    }
+
     const copy = async (sample: CodeSample) => {
+        const payload = await loadSample(sample)
+        if (!payload) return
+
         showCopyFeedback(sample.id)
         if (typeof navigator === 'undefined' || !navigator.clipboard) return
         try {
-            await navigator.clipboard.writeText(sample.code)
+            await navigator.clipboard.writeText(payload.code)
         } catch {
             /* clipboard blocked — fail quiet, the user can select + copy */
         }
     }
 
+    onMount(() => {
+        for (const sample of samples) {
+            if (!isLazySample(sample)) continue
+            const samplePreload = sample.preload ?? preload
+            if (samplePreload === 'idle') scheduleIdlePreload(sample)
+        }
+    })
+
     onDestroy(() => {
         if (copyResetTimer) clearTimeout(copyResetTimer)
+        for (const cancel of cancelPreloads) cancel()
     })
 
     const copyPress = { scale: 0.96 }
@@ -106,6 +212,9 @@
 
 <div class="dk-coderef" style="--dk-coderef-cols: {colCount}">
     {#each samples as sample (sample.id)}
+        {@const payload = getPayload(sample)}
+        {@const isLoading = Boolean(loadingById[sample.id])}
+        {@const hasError = Boolean(errorById[sample.id])}
         <article class="dk-coderef-cell">
             <header class="dk-coderef-head">
                 <div class="dk-coderef-meta">
@@ -119,6 +228,8 @@
                     onclick={() => copy(sample)}
                     whileTap={copyPress}
                     whileHover={copyHover}
+                    disabled={isLoading}
+                    aria-busy={isLoading}
                 >
                     <AnimatePresence initial={false}>
                         {#if copiedId === sample.id}
@@ -133,6 +244,17 @@
                                 <CheckIcon size={11} />
                                 <span>copied</span>
                             </MotionSpan>
+                        {:else if isLoading}
+                            <MotionSpan
+                                key="loading"
+                                class="dk-coderef-copy-state loading-state"
+                                initial={{ opacity: 1, y: 0 }}
+                                animate={{ opacity: 1, y: 0 }}
+                                exit={{ opacity: 0, y: 0 }}
+                                transition={copyStateTransition}
+                            >
+                                <span>loading</span>
+                            </MotionSpan>
                         {:else}
                             <MotionSpan
                                 key="copy"
@@ -150,13 +272,23 @@
                 </MotionButton>
             </header>
             <div class="dk-coderef-code">
-                {#if sample.html}
+                {#if payload?.html}
                     <!-- eslint-disable-next-line svelte/no-at-html-tags -- shiki-rendered HTML supplied by the consumer; treat as trusted input -->
-                    <div class="shiki-light">{@html sample.html.light}</div>
+                    <div class="shiki-light">{@html payload.html.light}</div>
                     <!-- eslint-disable-next-line svelte/no-at-html-tags -- shiki-rendered HTML supplied by the consumer; treat as trusted input -->
-                    <div class="shiki-dark">{@html sample.html.dark}</div>
+                    <div class="shiki-dark">{@html payload.html.dark}</div>
+                {:else if payload}
+                    <pre><code>{payload.code}</code></pre>
+                {:else if hasError}
+                    <div class="dk-coderef-placeholder">
+                        <strong>failed to load code</strong>
+                        <span>try reopening the panel</span>
+                    </div>
                 {:else}
-                    <pre><code>{sample.code}</code></pre>
+                    <div class="dk-coderef-placeholder">
+                        <strong>loading code</strong>
+                        <span>fetching the highlighted snippet</span>
+                    </div>
                 {/if}
             </div>
         </article>
@@ -251,6 +383,10 @@
             color-mix(in srgb, var(--brut-accent) 10%, transparent)
         );
     }
+    .dk-coderef :global(.dk-coderef-copy:disabled) {
+        cursor: progress;
+        opacity: 0.72;
+    }
     .dk-coderef :global(.dk-coderef-copy-state) {
         display: inline-flex;
         align-items: center;
@@ -267,6 +403,9 @@
     .dk-coderef :global(.dk-coderef-copy-state.copied-state) {
         color: var(--brut-accent);
     }
+    .dk-coderef :global(.dk-coderef-copy-state.loading-state) {
+        color: var(--brut-ink-3);
+    }
 
     /* ── Code area — fills the cell so the scrollbar sits flush ───── */
     .dk-coderef-code {
@@ -309,6 +448,24 @@
         font-family: inherit;
         background: transparent;
     }
+    .dk-coderef-placeholder {
+        display: grid;
+        min-height: 180px;
+        place-content: center;
+        gap: 6px;
+        padding: 28px 18px;
+        background: var(--brut-bg);
+        color: var(--brut-ink-3);
+        text-align: center;
+    }
+    .dk-coderef-placeholder strong {
+        color: var(--brut-ink);
+        font-size: 12px;
+        text-transform: uppercase;
+    }
+    .dk-coderef-placeholder span {
+        font-size: 11px;
+    }
 
     /* Light/dark switching for shiki-rendered samples. Prose.css scopes
        its toggle to `.prose`, so we re-state it here on the grid root to

src/lib/index.ts

@@ -47,6 +47,8 @@ export type { NavItem, NavSection } from './types/nav.js'
 export {
     formatSheetLabel,
     type DemoManifestEntry,
+    type DemoManifestIndex,
+    type DemoManifestIndexEntry,
     type ExampleSection
 } from './types/example-section.js'
 

src/lib/types/example-section.ts

@@ -76,6 +76,23 @@ export interface DemoManifestEntry {
     html?: { light: string; dark: string }
 }
 
+/**
+ * Shape of one entry in the split `demo-manifest.json` emitted when
+ * `demoManifestPlugin({ split: true })` is enabled. The heavy source and
+ * Shiki HTML live behind `importPath`, which can be loaded after hydration
+ * or when a code panel opens.
+ */
+export interface DemoManifestIndexEntry {
+    /** Virtual module import path for this demo's full `DemoManifestEntry`. */
+    importPath: string
+    /** Size of the copyable source text in bytes. Useful for diagnostics. */
+    codeBytes: number
+    /** Combined size of the light + dark Shiki HTML in bytes. */
+    htmlBytes: number
+}
+
+export type DemoManifestIndex = Record<string, DemoManifestIndexEntry>
+
 /**
  * Format an index + total into the brutalist sheet label, e.g.
  * `formatSheetLabel(0, 12) === "SHEET 01 / 12"`. Pure presentation — drop in

src/lib/virtual-demo.d.ts

@@ -0,0 +1,10 @@
+declare module 'virtual:docs-kit/demo/*' {
+    interface DemoManifestEntry {
+        code: string
+        lang: string
+        html?: { light: string; dark: string }
+    }
+
+    const entry: DemoManifestEntry
+    export default entry
+}