From be963864d0e55028d30991ac677409f63a35426d Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Tue, 2 Jun 2026 17:28:37 -0400
Subject: [PATCH 01/22] docs: generate sitemap manifest in Vite

---
 .github/workflows/cloudflare-deploy.yml    |   6 +-
 docs/package.json                          |   6 +-
 docs/scripts/generate-sitemap-manifest.mjs | 153 ---------------------
 docs/vite.config.ts                        |   8 +-
 pnpm-lock.yaml                             |  10 +-
 5 files changed, 17 insertions(+), 166 deletions(-)
 delete mode 100644 docs/scripts/generate-sitemap-manifest.mjs

diff --git a/.github/workflows/cloudflare-deploy.yml b/.github/workflows/cloudflare-deploy.yml
index 21a5360..cd2a327 100644
--- a/.github/workflows/cloudflare-deploy.yml
+++ b/.github/workflows/cloudflare-deploy.yml
@@ -47,9 +47,9 @@ jobs:
             - name: Build Package
               run: pnpm run build
 
-            - name: Generate sitemap manifest
-              working-directory: docs
-              run: pnpm run sitemap:manifest
+            # The sitemap manifest now emits from docs-kit's
+            # `sitemapManifestPlugin` in `docs/vite.config.ts`, which runs
+            # automatically during the Vite build inside `pnpm run deploy`.
 
             - name: Deploy Docs
               working-directory: docs
diff --git a/docs/package.json b/docs/package.json
index c23103d..c87c4e7 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -4,15 +4,13 @@
     "private": true,
     "type": "module",
     "scripts": {
-        "build": "tsx ./scripts/fetch-github-stats.ts && node ./scripts/generate-sitemap-manifest.mjs && tsx ./scripts/generate-social-cards.ts && vite build",
+        "build": "tsx ./scripts/fetch-github-stats.ts && tsx ./scripts/generate-social-cards.ts && vite build",
         "cf-typegen": "wrangler types && mv worker-configuration.d.ts src/",
         "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
         "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
         "deploy": "npm run build && wrangler deploy",
         "dev": "vite dev",
         "generate-social": "tsx ./scripts/generate-social-cards.ts",
-        "sitemap:manifest": "node ./scripts/generate-sitemap-manifest.mjs",
-        "sitemap:watch": "chokidar 'src/routes/**/*.svelte' 'src/routes/**/*.svx' 'src/routes/**/*.md' --ignore 'src/routes/examples/+page.ts' -c 'node ./scripts/generate-sitemap-manifest.mjs' --initial --silent",
         "social:watch": "chokidar 'src/lib/components/OG.svelte' 'scripts/generate-social-cards.ts' -c 'tsx ./scripts/generate-social-cards.ts' --initial --silent",
         "format": "prettier --write .",
         "lint": "prettier --check . && eslint .",
@@ -20,7 +18,7 @@
         "preview": "vite preview"
     },
     "dependencies": {
-        "@humanspeak/docs-kit": "github:humanspeak/docs-kit#2026.6.4",
+        "@humanspeak/docs-kit": "github:humanspeak/docs-kit#2026.6.5",
         "@humanspeak/memory-cache": "workspace:*",
         "@humanspeak/svelte-markdown": "^1.5.4",
         "github-slugger": "^2.0.0",
diff --git a/docs/scripts/generate-sitemap-manifest.mjs b/docs/scripts/generate-sitemap-manifest.mjs
deleted file mode 100644
index d9823a0..0000000
--- a/docs/scripts/generate-sitemap-manifest.mjs
+++ /dev/null
@@ -1,153 +0,0 @@
-import { readdir, readFile, stat, writeFile } from 'node:fs/promises'
-import { join, resolve as resolvePath } from 'node:path'
-
-const ROOT = resolvePath(process.cwd(), 'src', 'routes')
-
-/** Convert a +page file path to a route path */
-function toRoutePath(file) {
-    let p = file.replace(ROOT, '')
-    p = p.replace(/\/\+page\.(svelte|svx|md)$/i, '')
-    return p === '' ? '/' : p
-}
-
-/** Recursively find +page files */
-async function findPageFiles(dir, out = []) {
-    const entries = await readdir(dir, { withFileTypes: true })
-    for (const e of entries) {
-        const full = join(dir, e.name)
-        if (e.isDirectory()) {
-            await findPageFiles(full, out)
-        } else if (/\+page\.(svelte|svx|md)$/i.test(e.name)) {
-            out.push(full)
-        }
-    }
-    return out
-}
-
-/**
- * Load example metadata from individual +page.ts files
- * @param {string} examplePath - Path to the example directory
- * @returns {Promise<Object|null>} Example metadata or null if not found
- */
-async function loadExampleMetadata(examplePath) {
-    try {
-        const pageTs = join(examplePath, '+page.ts')
-        const content = await readFile(pageTs, 'utf8')
-
-        // Extract title from the load function return
-        const titleMatch = content.match(/title:\s*['"`]([^'"`]+)['"`]/)
-        const sourceUrlMatch = content.match(/sourceUrl:\s*['"`]([^'"`]+)['"`]/)
-
-        if (titleMatch) {
-            return {
-                title: titleMatch[1],
-                sourceUrl: sourceUrlMatch?.[1] || null
-            }
-        }
-    } catch {
-        // File doesn't exist or can't be read, that's okay
-    }
-    return null
-}
-
-/**
- * Generate example metadata for the examples landing page
- * @param {Object} manifest - The sitemap manifest
- * @returns {Promise<Object>} Examples metadata object
- */
-async function generateExamplesMetadata(manifest) {
-    const exampleRoutes = Object.keys(manifest)
-        .filter((route) => route.startsWith('/examples/') && route !== '/examples')
-        .sort()
-
-    const examples = {}
-
-    for (const route of exampleRoutes) {
-        const slug = route.replace('/examples/', '')
-        const examplePath = join(ROOT, 'examples', slug)
-
-        // Try to load metadata from the example's +page.ts file
-        const metadata = await loadExampleMetadata(examplePath)
-
-        if (metadata) {
-            const title = metadata.title
-            examples[slug] = {
-                title,
-                description: `Interactive ${title.toLowerCase()} animation example using Svelte Motion.`,
-                sourceUrl: metadata.sourceUrl
-            }
-        } else {
-            // Fallback: generate from slug
-            const title = slug
-                .split('-')
-                .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-                .join(' ')
-
-            examples[slug] = {
-                title,
-                description: `Interactive ${title.toLowerCase()} animation example using Svelte Motion.`,
-                sourceUrl: null
-            }
-        }
-    }
-
-    return examples
-}
-
-/**
- * Update the examples +page.ts file with the latest example metadata
- * @param {Object} examples - Examples metadata object
- */
-async function updateExamplesPageTs(examples) {
-    const examplesPageTs = resolvePath(process.cwd(), 'src', 'routes', 'examples', '+page.ts')
-
-    try {
-        let content = await readFile(examplesPageTs, 'utf8')
-
-        // Find the examples object in the file and replace it
-        // More robust regex that matches the entire examples object declaration
-        const examplesObjectRegex = /const examples\s*=\s*\{[\s\S]*?\n\s*\}(?=\s*\n\s*return)/
-        // Format as JS object literal with single quotes and unquoted keys (matching prettier config)
-        const jsObject = JSON.stringify(examples, null, 4)
-            .replace(/"([^"]+)":/g, (_, key) =>
-                /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? `${key}:` : `'${key}':`
-            )
-            .replace(/: "([^"]*)"/g, (_, value) => `: '${value}'`)
-            .replace(/: null/g, ': null')
-        const newExamplesObject = `const examples = ${jsObject.replace(/^/gm, '    ').trim()}`
-
-        if (examplesObjectRegex.test(content)) {
-            content = content.replace(examplesObjectRegex, newExamplesObject)
-            await writeFile(examplesPageTs, content, 'utf8')
-            console.log(`Updated examples metadata in ${examplesPageTs}`)
-        } else {
-            console.warn(`Could not find examples object pattern in ${examplesPageTs}`)
-        }
-    } catch (error) {
-        console.warn(`Could not update examples page: ${error.message}`)
-    }
-}
-
-async function main() {
-    const files = await findPageFiles(ROOT)
-    const manifest = {}
-    for (const file of files) {
-        const s = await stat(file)
-        const route = toRoutePath(file)
-        // Non-recursive lastmod: use the +page file's mtime only
-        manifest[route] = new Date(s.mtimeMs).toISOString().slice(0, 10)
-    }
-
-    const dest = resolvePath(process.cwd(), 'src', 'lib', 'sitemap-manifest.json')
-    await writeFile(dest, JSON.stringify(manifest, null, 2) + '\n', 'utf8')
-    console.log(`Sitemap manifest written to ${dest}`)
-
-    // Generate and update examples metadata
-    const examples = await generateExamplesMetadata(manifest)
-    await updateExamplesPageTs(examples)
-}
-
-main().catch((err) => {
-    console.error(err)
-    process.exit(1)
-})
diff --git a/docs/vite.config.ts b/docs/vite.config.ts
index 1600bba..da613f0 100644
--- a/docs/vite.config.ts
+++ b/docs/vite.config.ts
@@ -1,4 +1,9 @@
-import { docMirrorsPlugin, llmsFullPlugin, llmsPlugin } from '@humanspeak/docs-kit/vite'
+import {
+    docMirrorsPlugin,
+    llmsFullPlugin,
+    llmsPlugin,
+    sitemapManifestPlugin
+} from '@humanspeak/docs-kit/vite'
 import { sveltekit } from '@sveltejs/kit/vite'
 import tailwindcss from '@tailwindcss/vite'
 import { defineConfig } from 'vite'
@@ -7,6 +12,7 @@ import { docsConfig } from './src/lib/docs-config'
 
 export default defineConfig({
     plugins: [
+        sitemapManifestPlugin({ blogDir: false }),
         docMirrorsPlugin({ siteUrl: docsConfig.url }),
         llmsFullPlugin({
             siteUrl: docsConfig.url,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index c3706d5..d9e2089 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -81,8 +81,8 @@ importers:
   docs:
     dependencies:
       '@humanspeak/docs-kit':
-        specifier: github:humanspeak/docs-kit#2026.6.4
-        version: https://codeload.github.com/humanspeak/docs-kit/tar.gz/20610949ada1a430ee9300b3a88367e4d9caffbb(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))
+        specifier: github:humanspeak/docs-kit#2026.6.5
+        version: https://codeload.github.com/humanspeak/docs-kit/tar.gz/e1198d98213319920f43eceaa83eef3a5b7854b1(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))
       '@humanspeak/memory-cache':
         specifier: workspace:*
         version: link:..
@@ -672,8 +672,8 @@ packages:
     resolution: {integrity: sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q==}
     engines: {node: '>=18.18.0'}
 
-  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/20610949ada1a430ee9300b3a88367e4d9caffbb':
-    resolution: {gitHosted: true, tarball: https://codeload.github.com/humanspeak/docs-kit/tar.gz/20610949ada1a430ee9300b3a88367e4d9caffbb}
+  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/e1198d98213319920f43eceaa83eef3a5b7854b1':
+    resolution: {gitHosted: true, integrity: sha512-6DRISAXr36xDU6zHqvAmCPZdY3tQJyjljfrj/dv8D6JAu3xrb2IdKbfZjGmRL+ACNpyBeEMyED8ZNJ1Q34RGrQ==, tarball: https://codeload.github.com/humanspeak/docs-kit/tar.gz/e1198d98213319920f43eceaa83eef3a5b7854b1}
     version: 0.0.0
     peerDependencies:
       '@humanspeak/svelte-markdown': '>=1.0.0'
@@ -3325,7 +3325,7 @@ snapshots:
 
   '@humanfs/types@0.15.0': {}
 
-  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/20610949ada1a430ee9300b3a88367e4d9caffbb(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))':
+  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/e1198d98213319920f43eceaa83eef3a5b7854b1(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))':
     dependencies:
       '@humanspeak/svelte-motion': 0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))
       '@humanspeak/svelte-satori-fix': 0.0.6(svelte@5.56.0(@typescript-eslint/types@8.60.0))

From d865b11f194029af3eb3ebb76bc19846db090915 Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Tue, 2 Jun 2026 17:33:44 -0400
Subject: [PATCH 02/22] docs: use updated docs header and footer

---
 docs/src/lib/components/general/Footer.svelte |  7 +++++--
 docs/src/lib/components/general/Header.svelte | 16 ++++++++++++++--
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/docs/src/lib/components/general/Footer.svelte b/docs/src/lib/components/general/Footer.svelte
index 459c2aa..d533c66 100644
--- a/docs/src/lib/components/general/Footer.svelte
+++ b/docs/src/lib/components/general/Footer.svelte
@@ -1,5 +1,8 @@
 <script lang="ts">
-    import { Footer } from '@humanspeak/docs-kit'
+    import { FooterV2 } from '@humanspeak/docs-kit'
+    import rootPkg from '../../../../../package.json'
+
+    const PKG_VERSION = rootPkg.version
 </script>
 
-<Footer />
+<FooterV2 version={PKG_VERSION} />
diff --git a/docs/src/lib/components/general/Header.svelte b/docs/src/lib/components/general/Header.svelte
index f2c4304..aeebae9 100644
--- a/docs/src/lib/components/general/Header.svelte
+++ b/docs/src/lib/components/general/Header.svelte
@@ -1,6 +1,18 @@
 <script lang="ts">
-    import { Header } from '@humanspeak/docs-kit'
+    import { HeaderV2 } from '@humanspeak/docs-kit'
     import { docsConfig } from '$lib/docs-config'
+    import favicon from '$lib/assets/logo.svg'
+    import rootPkg from '../../../../../package.json'
+
+    const PKG_VERSION = rootPkg.version
 </script>
 
-<Header config={docsConfig} favicon="/logo.svg" />
+<HeaderV2
+    config={docsConfig}
+    {favicon}
+    version={PKG_VERSION}
+    nav={[
+        { label: 'docs', href: '/docs' },
+        { label: 'examples', href: '/examples' }
+    ]}
+/>

From e5cae1749ad580629731f3b5626697be33f58cee Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Tue, 2 Jun 2026 18:01:02 -0400
Subject: [PATCH 03/22] docs: update docs pages to V2 layout

- Use docs-kit V2 layout, sidebar, slug strip, and TOC components
- Import upstream docs-kit brutalist and prose styles
- Add Lucide section icons for docs navigation
---
 docs/src/app.css                            |  56 +++++++
 docs/src/lib/docsNav.ts                     |   4 +
 docs/src/routes/docs/+layout.svelte         | 168 +++++++++++---------
 docs/src/routes/docs/TableOfContents.svelte | 145 -----------------
 4 files changed, 152 insertions(+), 221 deletions(-)
 delete mode 100644 docs/src/routes/docs/TableOfContents.svelte

diff --git a/docs/src/app.css b/docs/src/app.css
index 3108ce4..c28668d 100644
--- a/docs/src/app.css
+++ b/docs/src/app.css
@@ -1,8 +1,34 @@
 @import 'tailwindcss';
 @source '../node_modules/@humanspeak/docs-kit/dist';
 @import '@humanspeak/docs-kit/styles/base.css';
+@import '@humanspeak/docs-kit/styles/brutalist.css';
+@import '@humanspeak/docs-kit/styles/prose-v2.css';
 @plugin '@tailwindcss/typography';
 
+/* Project-specific tokens */
+:root {
+    --color-success: #22c55e;
+}
+
+.dark {
+    --color-success: #4ade80;
+}
+
+@theme inline {
+    --color-success: var(--color-success);
+}
+
+/* Shiki theme switching outside .prose */
+@layer base {
+    html:not(.dark) .shiki-dark {
+        display: none;
+    }
+
+    html.dark .shiki-light {
+        display: none;
+    }
+}
+
 /* Project-specific: landing page decorative styles */
 .orb-a-bg {
     background: radial-gradient(
@@ -34,3 +60,33 @@
     background-size: 200% 100%;
     animation: sheen 6s ease-in-out infinite;
 }
+
+.shiny-button {
+    --radial-gradient-background: 250, 250, 250;
+    --solid-color-background: 15, 15, 15;
+    --overlay-color: 255, 255, 255;
+}
+
+/* Project-specific: ComponentSource dialog */
+.component-source-dialog {
+    @apply border-border bg-background fixed inset-4 z-50 flex flex-col overflow-hidden rounded-xl border shadow-2xl;
+    max-width: 1100px;
+    max-height: 80vh;
+    margin: auto;
+}
+
+.component-source-code pre.shiki {
+    @apply m-0 rounded-none bg-transparent! p-4;
+    counter-reset: line;
+}
+
+.component-source-code pre.shiki code {
+    @apply bg-transparent!;
+    counter-reset: line;
+}
+
+.component-source-code pre.shiki code .line::before {
+    counter-increment: line;
+    content: counter(line);
+    @apply text-muted-foreground/50 mr-6 inline-block w-4 text-right;
+}
diff --git a/docs/src/lib/docsNav.ts b/docs/src/lib/docsNav.ts
index b3b76f3..8e971a3 100644
--- a/docs/src/lib/docsNav.ts
+++ b/docs/src/lib/docsNav.ts
@@ -20,6 +20,7 @@ import Timer from '@lucide/svelte/icons/timer'
 export const docsSections: NavSection[] = [
     {
         title: 'Get Started',
+        icon: Rocket,
         items: [
             {
                 title: 'Getting Started',
@@ -30,6 +31,7 @@ export const docsSections: NavSection[] = [
     },
     {
         title: 'Interactive Demos',
+        icon: Play,
         items: [
             { title: 'All Examples', href: '/examples', icon: Play, exact: true },
             { title: 'Basic Cache', href: '/examples/basic-cache', icon: Box },
@@ -40,6 +42,7 @@ export const docsSections: NavSection[] = [
     },
     {
         title: 'API Reference',
+        icon: Database,
         items: [
             { title: 'MemoryCache', href: '/docs/api/memory-cache', icon: Database },
             { title: '@cached Decorator', href: '/docs/api/cached-decorator', icon: AtSign }
@@ -47,6 +50,7 @@ export const docsSections: NavSection[] = [
     },
     {
         title: 'Examples',
+        icon: Code,
         items: [
             { title: 'Overview', href: '/docs/examples', icon: Code, exact: true },
             { title: 'Configuration', href: '/docs/examples/configuration', icon: Sliders },
diff --git a/docs/src/routes/docs/+layout.svelte b/docs/src/routes/docs/+layout.svelte
index 07eab94..87d5cad 100644
--- a/docs/src/routes/docs/+layout.svelte
+++ b/docs/src/routes/docs/+layout.svelte
@@ -1,100 +1,116 @@
 <script lang="ts">
+    import { afterNavigate } from '$app/navigation'
     import { page } from '$app/state'
-    import GithubSlugger from 'github-slugger'
-    import Header from '$lib/components/general/Header.svelte'
-    import Footer from '$lib/components/general/Footer.svelte'
-    import { Sidebar, getBreadcrumbContext, getDocsTitleByPath, enhanceCodeBlocks } from '@humanspeak/docs-kit'
+    import {
+        DocSlugStrip,
+        FooterV2,
+        HeaderV2,
+        SidebarV2,
+        TableOfContentsV2,
+        enhanceCodeBlocks,
+        extractHeadings,
+        getBreadcrumbContext,
+        type TocHeading
+    } from '@humanspeak/docs-kit'
+    import favicon from '$lib/assets/logo.svg'
     import { docsConfig } from '$lib/docs-config'
     import { docsSections } from '$lib/docsNav'
-    import TableOfContents from './TableOfContents.svelte'
+    import sitemapManifest from '$lib/sitemap-manifest.json'
+    import rootPkg from '../../../../package.json'
+
+    const BASE_URL = 'https://memory.svelte.page'
+    const PKG_VERSION = rootPkg.version
 
     const { children, data } = $props()
 
-    const breadcrumbContext = getBreadcrumbContext()
-    $effect(() => {
-        if (breadcrumbContext) {
-            const title = getDocsTitleByPath(docsSections, page.url.pathname)
-            breadcrumbContext.breadcrumbs =
-                title && page.url.pathname !== '/docs'
-                    ? [{ title: 'Docs', href: '/docs' }, { title }]
-                    : [{ title: 'Docs' }]
-        }
+    const docSlug = $derived.by(() => {
+        const path = page.url.pathname.replace(/\/+$/, '')
+        if (path === '/docs' || path === '') return 'index'
+        return path.replace('/docs/', '')
     })
 
     let contentElement: HTMLElement | undefined = $state(undefined)
-    let headings: { id: string; text: string; level: number; element: HTMLElement }[] = $state([])
-
-    /**
-     * Extract headings from content for table of contents
-     * Generates descriptive, slugified IDs for better URL anchors using github-slugger
-     */
-    function extractHeadings() {
-        if (!contentElement) return
-
-        const headingElements = contentElement.querySelectorAll('h1, h2, h3, h4, h5, h6')
-        const slugger = new GithubSlugger()
-
-        headings = Array.from(headingElements).map((el, index) => {
-            const text = el.textContent?.trim() || ''
-            const level = parseInt(el.tagName.charAt(1))
-
-            // Use existing ID if present, otherwise generate slug
-            let id = el.id
-            if (!id) {
-                id = text ? slugger.slug(text) : `heading-${index}`
-            }
-
-            if (!el.id) {
-                el.id = id
-            }
+    let headings: TocHeading[] = $state([])
 
-            return {
-                id,
-                text,
-                level,
-                element: el as HTMLElement
-            }
-        })
+    const breadcrumbContext = getBreadcrumbContext()
+    if (breadcrumbContext) {
+        const initialTitle = (page.data?.title as string | undefined) || 'Getting Started'
+        breadcrumbContext.breadcrumbs = [{ title: 'Docs', href: '/docs' }, { title: initialTitle }]
     }
-
-    // Setup MutationObserver to watch for DOM changes and initial extraction
     $effect(() => {
-        if (!contentElement) return
+        if (!breadcrumbContext) return
+        const title = (page.data?.title as string | undefined) || 'Getting Started'
+        breadcrumbContext.breadcrumbs = [{ title: 'Docs', href: '/docs' }, { title }]
+    })
 
-        // Initial extraction
-        extractHeadings()
+    const techArticleJsonLd = $derived.by(() => {
+        const title = page.data?.title as string | undefined
+        const description = page.data?.description as string | undefined
+        if (!title) return ''
+        const pathname = page.url.pathname
+        const lastmod =
+            (sitemapManifest as Record<string, string>)[pathname] ??
+            new Date().toISOString().split('T')[0]
+        return `<${'script'} type="application/ld+json">${JSON.stringify({
+            '@context': 'https://schema.org',
+            '@type': 'TechArticle',
+            headline: title,
+            description: description || title,
+            url: `${BASE_URL}${pathname}`,
+            dateModified: lastmod,
+            author: {
+                '@type': 'Organization',
+                name: 'Humanspeak',
+                url: 'https://humanspeak.com'
+            },
+            publisher: {
+                '@type': 'Organization',
+                name: 'Humanspeak',
+                url: 'https://humanspeak.com'
+            },
+            proficiencyLevel: 'Beginner'
+        })}</${'script'}>`
+    })
 
-        // Watch for DOM mutations (new content loaded via navigation)
-        let rafId: number | null = null
-        const observer = new MutationObserver(() => {
-            if (rafId) cancelAnimationFrame(rafId)
-            rafId = requestAnimationFrame(() => {
-                rafId = null
-                extractHeadings()
-            })
-        })
+    const refreshHeadings = () => {
+        if (contentElement) headings = extractHeadings(contentElement)
+    }
 
-        observer.observe(contentElement, {
-            childList: true,
-            subtree: true
-        })
+    $effect(() => {
+        if (contentElement) refreshHeadings()
+    })
 
-        return () => {
-            if (rafId) cancelAnimationFrame(rafId)
-            observer.disconnect()
-        }
+    afterNavigate(() => {
+        requestAnimationFrame(refreshHeadings)
     })
 </script>
 
+<svelte:head>
+    {#if techArticleJsonLd}
+        <!-- trunk-ignore(eslint/svelte/no-at-html-tags) -->
+        {@html techArticleJsonLd}
+    {/if}
+</svelte:head>
+
 <div class="flex min-h-screen flex-col justify-between bg-background">
-    <Header />
+    <HeaderV2
+        config={docsConfig}
+        {favicon}
+        version={PKG_VERSION}
+        nav={[
+            { label: 'docs', href: '/docs' },
+            { label: 'examples', href: '/examples' }
+        ]}
+    />
+
+    <DocSlugStrip slug={docSlug} />
 
     <div class="flex flex-1">
         <!-- Left sidebar - Navigation -->
         <aside
             class="hidden w-64 shrink-0 border-r border-sidebar-border bg-sidebar-background/95 shadow-sm lg:sticky lg:top-0 lg:block lg:h-screen lg:overflow-y-auto"
         >
-            <Sidebar
+            <SidebarV2
                 config={docsConfig}
                 sections={docsSections}
                 currentPath={page.url.pathname}
@@ -103,16 +119,16 @@
         </aside>
 
         <!-- Main content area -->
-        <main class="flex-1">
-            <div class="flex">
+        <main class="min-w-0 flex-1">
+            <div class="flex min-w-0">
                 <!-- Content -->
                 <article
                     bind:this={contentElement}
                     use:enhanceCodeBlocks
-                    class="flex-1 px-4 py-8 sm:px-6 lg:px-8"
+                    class="min-w-0 flex-1 px-4 py-8 sm:px-6 lg:px-8"
                 >
                     <div
-                        class="prose max-w-none text-text-primary prose-slate dark:prose-invert prose-headings:scroll-mt-20"
+                        class="prose-v2 prose max-w-none text-text-primary prose-slate dark:prose-invert prose-headings:scroll-mt-20"
                     >
                         {@render children()}
                     </div>
@@ -122,10 +138,10 @@
                 <aside
                     class="hidden w-56 shrink-0 border-l border-sidebar-border bg-sidebar-background/95 shadow-sm xl:sticky xl:top-0 xl:block xl:h-screen xl:overflow-y-auto"
                 >
-                    <TableOfContents {headings} />
+                    <TableOfContentsV2 {headings} />
                 </aside>
             </div>
         </main>
     </div>
-    <Footer />
+    <FooterV2 version={PKG_VERSION} />
 </div>
diff --git a/docs/src/routes/docs/TableOfContents.svelte b/docs/src/routes/docs/TableOfContents.svelte
deleted file mode 100644
index 07e9516..0000000
--- a/docs/src/routes/docs/TableOfContents.svelte
+++ /dev/null
@@ -1,145 +0,0 @@
-<!--
-  @component
-  Right sidebar table of contents component (Svelte 5 + TypeScript)
-  Auto-generated from page headings with smooth scroll and active section tracking
-
-  @prop {TocHeading[]} headings - Array of heading objects with id, text, level, and element reference
--->
-<script lang="ts">
-    import { afterNavigate } from '$app/navigation'
-    export type TocHeading = {
-        id: string
-        text: string
-        level: number
-        element: HTMLElement
-    }
-
-    const { headings = [] } = $props<{ headings: TocHeading[] }>()
-
-    let activeHeading = $state<string>('')
-
-    /**
-     * Smoothly scrolls to a heading element by its ID
-     * Accounts for header offset to ensure heading is at top of viewport
-     */
-    function scrollToHeading(id: string) {
-        const element = document.getElementById(id)
-        if (element) {
-            // Optimistically set active for immediate feedback
-            activeHeading = id
-
-            // Calculate position accounting for any offset (headers, padding)
-            const elementPosition = element.getBoundingClientRect().top
-            const offsetPosition = elementPosition + window.scrollY - 20 // 20px offset from top
-
-            window.scrollTo({
-                top: offsetPosition,
-                behavior: 'smooth'
-            })
-        }
-    }
-
-    /**
-     * Updates the active heading based on scroll position
-     * Finds the topmost visible heading within 100px of viewport top
-     */
-    function updateActiveHeading() {
-        // Reset if no headings
-        if (headings.length === 0) {
-            activeHeading = ''
-            return
-        }
-
-        // Find the last heading that's above the threshold
-        for (let i = headings.length - 1; i >= 0; i--) {
-            const heading = headings[i]
-            if (heading?.element) {
-                const rect = heading.element.getBoundingClientRect()
-                if (rect.top <= 100) {
-                    activeHeading = heading.id
-                    return
-                }
-            }
-        }
-
-        // Default to first heading if none are in view
-        if (headings[0]?.id) {
-            activeHeading = headings[0].id
-        }
-    }
-
-    // Find the nearest scrollable container for the first heading
-    function getScrollContainer(start: HTMLElement | undefined): HTMLElement | Window {
-        if (!start) return window
-        let node: HTMLElement | null = start.parentElement
-        while (node && node !== document.body) {
-            const style = getComputedStyle(node)
-            const overflowY = style.overflowY
-            if (
-                (overflowY === 'auto' || overflowY === 'scroll') &&
-                node.scrollHeight > node.clientHeight
-            ) {
-                return node
-            }
-            node = node.parentElement
-        }
-        return window
-    }
-
-    // React to heading changes (page navigation) and setup/cleanup scroll listener
-    $effect(() => {
-        // Reset and update when headings change
-        activeHeading = ''
-        updateActiveHeading()
-
-        // Setup scroll listener on the correct scroll container
-        const container = getScrollContainer(headings[0]?.element)
-        const add = (target: HTMLElement | Window) =>
-            target.addEventListener('scroll', updateActiveHeading)
-        const remove = (target: HTMLElement | Window) =>
-            target.removeEventListener('scroll', updateActiveHeading)
-        add(container)
-        // Also update on window resize (layout shifts)
-        window.addEventListener('resize', updateActiveHeading)
-
-        return () => {
-            remove(container)
-            window.removeEventListener('resize', updateActiveHeading)
-        }
-    })
-
-    // Update when the route changes (client-side navigation)
-    afterNavigate(() => {
-        // Allow DOM to settle across frames, then recompute
-        requestAnimationFrame(() => {
-            requestAnimationFrame(() => {
-                updateActiveHeading()
-            })
-        })
-    })
-</script>
-
-{#if headings.length > 0}
-    <nav class="p-6">
-        <h3 class="mb-4 text-sm font-semibold tracking-wide text-text-primary uppercase">
-            On this page
-        </h3>
-        <ul class="space-y-2 text-sm">
-            {#each headings as heading (heading.id)}
-                <li style="margin-left: {(heading.level - 1) * 12}px">
-                    <button
-                        type="button"
-                        onclick={() => scrollToHeading(heading.id)}
-                        class="block text-left transition-colors duration-150 hover:text-accent
-						{activeHeading === heading.id ? 'font-medium text-accent' : 'text-text-secondary'}"
-                    >
-                        {heading.text}
-                    </button>
-                </li>
-            {/each}
-        </ul>
-    </nav>
-{/if}
-
-
-

From 3530dbe3666059cee27834527aecfd2ca58d4b6d Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Tue, 2 Jun 2026 18:16:41 -0400
Subject: [PATCH 04/22] docs: update examples index to V2 layout

- Use the upstream docs-kit examples shell and BrutIndexV2 index
- Drive example cards from the sitemap manifest and page metadata
- Update the examples sitemap lastmod
---
 docs/src/lib/sitemap-manifest.json      |   2 +-
 docs/src/routes/examples/+layout.svelte |  28 +++-
 docs/src/routes/examples/+page.svelte   | 205 +++++++++++-------------
 docs/src/routes/examples/+page.ts       |  31 +++-
 4 files changed, 140 insertions(+), 126 deletions(-)

diff --git a/docs/src/lib/sitemap-manifest.json b/docs/src/lib/sitemap-manifest.json
index 2e2e42d..e2ff875 100644
--- a/docs/src/lib/sitemap-manifest.json
+++ b/docs/src/lib/sitemap-manifest.json
@@ -14,7 +14,7 @@
   "/docs/examples/service-class": "2026-03-15",
   "/docs/examples/sessions": "2026-03-15",
   "/docs/getting-started": "2026-03-09",
-  "/examples": "2026-03-05",
+  "/examples": "2026-06-02",
   "/examples/basic-cache": "2026-03-05",
   "/examples/cache-statistics": "2026-03-05",
   "/examples/lru-eviction": "2026-03-05",
diff --git a/docs/src/routes/examples/+layout.svelte b/docs/src/routes/examples/+layout.svelte
index 7c035d5..b0bff12 100644
--- a/docs/src/routes/examples/+layout.svelte
+++ b/docs/src/routes/examples/+layout.svelte
@@ -1,14 +1,26 @@
 <script lang="ts">
-    import Header from '$lib/components/general/Header.svelte'
-    import Footer from '$lib/components/general/Footer.svelte'
+    import { enhanceCodeBlocks, ExampleLayoutV2 } from '@humanspeak/docs-kit'
+    import { MotionConfig } from '@humanspeak/svelte-motion'
+    import favicon from '$lib/assets/logo.svg'
+    import { docsConfig } from '$lib/docs-config'
+    import rootPkg from '../../../../package.json'
 
     const { children } = $props()
+    const PKG_VERSION = rootPkg.version
 </script>
 
-<div class="relative flex min-h-screen flex-col bg-background">
-    <Header />
-    <div class="flex flex-1 flex-col">
-        {@render children?.()}
+<ExampleLayoutV2
+    config={docsConfig}
+    {favicon}
+    version={PKG_VERSION}
+    nav={[
+        { label: 'docs', href: '/docs' },
+        { label: 'examples', href: '/examples' }
+    ]}
+>
+    <div class="flex flex-1 flex-col" use:enhanceCodeBlocks>
+        <MotionConfig transition={{ duration: 0.6 }}>
+            {@render children?.()}
+        </MotionConfig>
     </div>
-    <Footer />
-</div>
+</ExampleLayoutV2>
diff --git a/docs/src/routes/examples/+page.svelte b/docs/src/routes/examples/+page.svelte
index 7dcf022..ec94fbe 100644
--- a/docs/src/routes/examples/+page.svelte
+++ b/docs/src/routes/examples/+page.svelte
@@ -1,12 +1,16 @@
 <script lang="ts">
-    import { getBreadcrumbContext, getSeoContext } from '@humanspeak/docs-kit'
-    import ArrowRight from '@lucide/svelte/icons/arrow-right'
-    import BarChart3 from '@lucide/svelte/icons/bar-chart-3'
-    import Box from '@lucide/svelte/icons/box'
-    import Clock from '@lucide/svelte/icons/clock'
-    import Layers from '@lucide/svelte/icons/layers'
-    import Rocket from '@lucide/svelte/icons/rocket'
-    import type { Component } from 'svelte'
+    import { BrutIndexV2, getBreadcrumbContext, getSeoContext } from '@humanspeak/docs-kit'
+    import sitemapManifest from '$lib/sitemap-manifest.json'
+    import type { PageData } from './$types'
+
+    type ExampleData = {
+        title: string
+        description: string
+    }
+
+    type ExamplesData = Record<string, ExampleData>
+
+    const { data }: { data: PageData } = $props()
 
     const breadcrumbs = getBreadcrumbContext()
     const seo = getSeoContext()
@@ -15,117 +19,88 @@
     }
     if (seo) {
         seo.title = 'Interactive Examples | Memory Cache'
-        seo.description = 'Explore interactive examples of @humanspeak/memory-cache featuring live demos of cache operations, TTL expiration, LRU eviction, and performance stats.'
+        seo.description =
+            'Explore interactive examples of @humanspeak/memory-cache featuring live demos of cache operations, TTL expiration, LRU eviction, and performance stats.'
+        seo.ogTitle = 'Examples'
+        seo.ogTagline = 'Interactive cache examples built with Memory Cache'
+        seo.ogFeatures = ['Basic Cache', 'TTL Expiration', 'LRU Eviction', 'Cache Statistics']
+        seo.ogSlug = 'examples'
     }
 
-    const examples: { slug: string; title: string; description: string; icon: Component }[] = [
-        {
-            slug: 'basic-cache',
-            title: 'Basic Cache',
-            description: 'Interactive demo of get, set, and delete operations with visual cache state.',
-            icon: Box
-        },
-        {
-            slug: 'ttl-expiration',
-            title: 'TTL Expiration',
-            description: 'Watch cache entries expire in real-time with countdown timers.',
-            icon: Clock
-        },
-        {
-            slug: 'lru-eviction',
-            title: 'LRU Eviction',
-            description: 'See how least recently used items are evicted when the cache is full.',
-            icon: Layers
-        },
-        {
-            slug: 'cache-statistics',
-            title: 'Cache Statistics',
-            description: 'Monitor hit rate, miss rate, and cache performance in real-time.',
-            icon: BarChart3
-        }
-    ]
-</script>
-
-<div class="container mx-auto px-4 py-12">
-    <!-- Hero Section -->
-    <div class="mb-12 text-center">
-        <h1 class="mb-4 bg-gradient-to-r from-brand-500 to-brand-600 bg-clip-text text-4xl font-bold text-transparent md:text-5xl">
-            Interactive Examples
-        </h1>
-        <p class="mx-auto max-w-2xl text-lg text-muted-foreground">
-            Explore how memory-cache works with live, interactive demos. See cache operations, TTL expiration, and LRU eviction in action.
-        </p>
-    </div>
-
-    <!-- Examples Grid -->
-    <div class="mx-auto grid max-w-4xl grid-cols-1 gap-6 md:grid-cols-2">
-        {#each examples as example, index}
-            {@const ExampleIcon = example.icon}
-            <a
-                href="/examples/{example.slug}"
-                class="example-card group relative overflow-hidden rounded-xl border border-border bg-card p-6 transition-all duration-300 hover:-translate-y-1 hover:border-brand-500/50 hover:shadow-lg hover:shadow-brand-500/10"
-                style="animation-delay: {index * 100}ms"
-            >
-                <!-- Gradient overlay -->
-                <div class="absolute inset-0 bg-gradient-to-br from-brand-500/5 to-transparent opacity-0 transition-opacity duration-300 group-hover:opacity-100"></div>
-
-                <div class="relative z-10">
-                    <!-- Icon -->
-                    <div class="mb-4 flex h-12 w-12 items-center justify-center rounded-lg bg-gradient-to-br from-brand-500 to-brand-600 text-white transition-transform duration-300 group-hover:scale-110">
-                        <ExampleIcon size={20} />
-                    </div>
+    const examples = $derived.by(() => {
+        const exampleRoutes = Object.keys(sitemapManifest)
+            .filter((route) => route.startsWith('/examples/') && route !== '/examples')
+            .sort()
 
-                    <h2 class="mb-2 text-xl font-semibold text-foreground transition-colors group-hover:text-brand-600">
-                        {example.title}
-                    </h2>
+        return exampleRoutes.map((route) => {
+            const slug = route.replace('/examples/', '')
+            const exampleData = (data.examples as ExamplesData)[slug]
+            const title = exampleData?.title || formatTitle(slug)
+            return {
+                route,
+                slug,
+                title,
+                description:
+                    exampleData?.description || `Interactive ${title.toLowerCase()} cache example`
+            }
+        })
+    })
 
-                    <p class="mb-4 text-sm text-muted-foreground">
-                        {example.description}
-                    </p>
-
-                    <div class="flex items-center text-sm font-medium text-brand-600 group-hover:text-brand-700">
-                        Try it
-                        <ArrowRight size={14} class="ml-2 transition-transform duration-200 group-hover:translate-x-1" />
-                    </div>
-                </div>
-
-                <!-- Decorative corner -->
-                <div class="absolute top-0 right-0 h-20 w-20 rounded-bl-full bg-gradient-to-bl from-brand-500/10 to-transparent opacity-0 transition-opacity duration-300 group-hover:opacity-100"></div>
-            </a>
-        {/each}
-    </div>
-
-    <!-- CTA Section -->
-    <div class="mt-16 text-center">
-        <div class="mx-auto max-w-xl rounded-2xl border border-brand-500/20 bg-gradient-to-r from-brand-500/10 to-brand-600/10 p-8">
-            <h2 class="mb-3 text-xl font-semibold text-foreground">Ready to use Memory Cache?</h2>
-            <p class="mb-6 text-muted-foreground">
-                Check out the documentation for installation and API reference.
-            </p>
-            <a
-                href="/docs/getting-started"
-                class="inline-flex items-center rounded-lg bg-gradient-to-r from-brand-500 to-brand-600 px-5 py-2.5 font-medium text-white transition-all duration-200 hover:from-brand-600 hover:to-brand-700"
-            >
-                Get Started
-                <Rocket size={14} class="ml-2" />
-            </a>
-        </div>
-    </div>
-</div>
-
-<style>
-    .example-card {
-        animation: fadeInUp 0.5s ease-out both;
+    function formatTitle(slug: string): string {
+        return slug
+            .split('-')
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ')
     }
 
-    @keyframes fadeInUp {
-        from {
-            opacity: 0;
-            transform: translateY(16px);
-        }
-        to {
-            opacity: 1;
-            transform: translateY(0);
+    const pad2 = (n: number) => String(n).padStart(2, '0')
+</script>
+
+<BrutIndexV2
+    hero={{
+        figLabel: 'FIG-001 · EXAMPLES INDEX',
+        figId: 'FIG-001',
+        sheetLabel: 'SHEET 01 / 02',
+        meta: [
+            { k: 'demos', v: String(examples.length) },
+            { k: 'format', v: 'live examples' },
+            { k: 'tone', v: 'interactive' },
+            { rule: 'dashed' },
+            { k: 'library', v: '@humanspeak/memory-cache' },
+            { k: 'runtime', v: 'typescript', accent: true },
+            { rule: 'dashed' }
+        ],
+        metaFooter: '// scroll for demos',
+        kicker: '// examples / live demos',
+        title: { accent: 'examples', end: '.' },
+        subHtml:
+            'Interactive cache demos built with <b>@humanspeak/memory-cache</b> — basic operations, TTL expiration, LRU eviction, and live cache statistics. Pick a card, inspect behavior, ship.',
+        ctas: [
+            {
+                label: 'browse basic-cache ↗',
+                href: '/examples/basic-cache',
+                primary: true
+            },
+            { label: 'get started', href: '/docs/getting-started' }
+        ]
+    }}
+    lede={{
+        kicker: 'FIG-002 / DEMOS',
+        title: { prefix: 'pick an ', accent: 'example', suffix: '.' },
+        body: 'Each page is a self-contained, interactive demo with the cache behavior you need.'
+    }}
+    items={examples.map((example, i) => ({
+        href: example.route,
+        id: `№ ${pad2(i + 1)} / ${pad2(examples.length)}`,
+        title: `${example.slug}.`,
+        line: example.description
+    }))}
+    footer={{
+        big: {
+            prefix: 'try ',
+            accent: 'basic-cache',
+            href: '/examples/basic-cache',
+            hint: 'set + get + delete operations'
         }
-    }
-</style>
+    }}
+/>
diff --git a/docs/src/routes/examples/+page.ts b/docs/src/routes/examples/+page.ts
index 266d635..4d96f86 100644
--- a/docs/src/routes/examples/+page.ts
+++ b/docs/src/routes/examples/+page.ts
@@ -1,5 +1,32 @@
-export const load = () => ({
+import type { PageLoad } from './$types'
+
+type ExampleEntry = {
+    title: string
+    description: string
+}
+
+const EXAMPLES: Record<string, ExampleEntry> = {
+    'basic-cache': {
+        title: 'Basic Cache',
+        description: 'Interactive demo of get, set, and delete operations with visual cache state.'
+    },
+    'ttl-expiration': {
+        title: 'TTL Expiration',
+        description: 'Watch cache entries expire in real time with countdown timers.'
+    },
+    'lru-eviction': {
+        title: 'LRU Eviction',
+        description: 'See how least recently used items are evicted when the cache is full.'
+    },
+    'cache-statistics': {
+        title: 'Cache Statistics',
+        description: 'Monitor hit rate, miss rate, and cache performance in real time.'
+    }
+}
+
+export const load: PageLoad = () => ({
     title: 'Interactive Examples | Memory Cache',
     description:
-        'Try interactive examples demonstrating Memory Cache features including TTL, LRU eviction, and cache statistics.'
+        'Try interactive examples demonstrating Memory Cache features including TTL, LRU eviction, and cache statistics.',
+    examples: EXAMPLES
 })

From 1ce1611c2d3892fd92734c5ff7867602345409b9 Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Tue, 2 Jun 2026 19:17:06 -0400
Subject: [PATCH 05/22] docs: add code panels to examples

- Generate demo manifests for example source snippets
- Move demo components into the upstream demos/Default.svelte shape
- Wire CodeReferenceV2 copy panels into individual example pages
- Ignore generated docs manifest files
---
 .gitignore                                    |  2 +
 .../demos/Default.svelte}                     |  0
 .../demos/Default.svelte}                     |  0
 .../demos/Default.svelte}                     |  0
 .../demos/Default.svelte}                     |  0
 docs/src/lib/sitemap-manifest.json            | 22 --------
 .../routes/examples/basic-cache/+page.svelte  | 50 ++++++++++++++++---
 .../examples/cache-statistics/+page.svelte    | 50 ++++++++++++++++---
 .../routes/examples/lru-eviction/+page.svelte | 50 ++++++++++++++++---
 .../examples/ttl-expiration/+page.svelte      | 50 ++++++++++++++++---
 docs/vite.config.ts                           | 14 ++++++
 11 files changed, 192 insertions(+), 46 deletions(-)
 rename docs/src/lib/examples/{BasicCache.svelte => basic-cache/demos/Default.svelte} (100%)
 rename docs/src/lib/examples/{CacheStatistics.svelte => cache-statistics/demos/Default.svelte} (100%)
 rename docs/src/lib/examples/{LruEviction.svelte => lru-eviction/demos/Default.svelte} (100%)
 rename docs/src/lib/examples/{TtlExpiration.svelte => ttl-expiration/demos/Default.svelte} (100%)
 delete mode 100644 docs/src/lib/sitemap-manifest.json

diff --git a/.gitignore b/.gitignore
index dfe1b86..a214fba 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,3 +30,5 @@ docs/static/llms-full.txt
 docs/static/llms.txt
 mprocs.log
 docs/src/lib/github-stats.json
+docs/src/lib/demo-manifest.json
+docs/src/lib/sitemap-manifest.json
diff --git a/docs/src/lib/examples/BasicCache.svelte b/docs/src/lib/examples/basic-cache/demos/Default.svelte
similarity index 100%
rename from docs/src/lib/examples/BasicCache.svelte
rename to docs/src/lib/examples/basic-cache/demos/Default.svelte
diff --git a/docs/src/lib/examples/CacheStatistics.svelte b/docs/src/lib/examples/cache-statistics/demos/Default.svelte
similarity index 100%
rename from docs/src/lib/examples/CacheStatistics.svelte
rename to docs/src/lib/examples/cache-statistics/demos/Default.svelte
diff --git a/docs/src/lib/examples/LruEviction.svelte b/docs/src/lib/examples/lru-eviction/demos/Default.svelte
similarity index 100%
rename from docs/src/lib/examples/LruEviction.svelte
rename to docs/src/lib/examples/lru-eviction/demos/Default.svelte
diff --git a/docs/src/lib/examples/TtlExpiration.svelte b/docs/src/lib/examples/ttl-expiration/demos/Default.svelte
similarity index 100%
rename from docs/src/lib/examples/TtlExpiration.svelte
rename to docs/src/lib/examples/ttl-expiration/demos/Default.svelte
diff --git a/docs/src/lib/sitemap-manifest.json b/docs/src/lib/sitemap-manifest.json
deleted file mode 100644
index e2ff875..0000000
--- a/docs/src/lib/sitemap-manifest.json
+++ /dev/null
@@ -1,22 +0,0 @@
-{
-  "/": "2026-03-05",
-  "/docs/api/cached-decorator": "2026-03-09",
-  "/docs/api/memory-cache": "2026-03-05",
-  "/docs/examples": "2026-03-05",
-  "/docs/examples/api-caching": "2026-03-15",
-  "/docs/examples/async-fetching": "2026-03-15",
-  "/docs/examples/computed-values": "2026-03-15",
-  "/docs/examples/configuration": "2026-03-15",
-  "/docs/examples/database-caching": "2026-03-15",
-  "/docs/examples/monitoring": "2026-03-15",
-  "/docs/examples/multi-tenant": "2026-03-15",
-  "/docs/examples/rate-limiting": "2026-03-15",
-  "/docs/examples/service-class": "2026-03-15",
-  "/docs/examples/sessions": "2026-03-15",
-  "/docs/getting-started": "2026-03-09",
-  "/examples": "2026-06-02",
-  "/examples/basic-cache": "2026-03-05",
-  "/examples/cache-statistics": "2026-03-05",
-  "/examples/lru-eviction": "2026-03-05",
-  "/examples/ttl-expiration": "2026-03-05"
-}
diff --git a/docs/src/routes/examples/basic-cache/+page.svelte b/docs/src/routes/examples/basic-cache/+page.svelte
index 8f2b20a..d4bb3bf 100644
--- a/docs/src/routes/examples/basic-cache/+page.svelte
+++ b/docs/src/routes/examples/basic-cache/+page.svelte
@@ -1,7 +1,17 @@
 <script lang="ts">
-    import { getBreadcrumbContext, getSeoContext } from '@humanspeak/docs-kit'
-    import Example from '$lib/components/general/Example.svelte'
-    import BasicCache from '$lib/examples/BasicCache.svelte'
+    import {
+        CodeReferenceV2,
+        type DemoManifestEntry,
+        ExampleV2,
+        getBreadcrumbContext,
+        getSeoContext
+    } from '@humanspeak/docs-kit'
+    import BasicCache from '$lib/examples/basic-cache/demos/Default.svelte'
+    import demoManifest from '$lib/demo-manifest.json'
+
+    const SOURCE_URL =
+        'https://github.com/humanspeak/memory-cache/blob/main/docs/src/lib/examples/'
+    const manifest = demoManifest as Record<string, DemoManifestEntry>
 
     const breadcrumbs = getBreadcrumbContext()
     const seo = getSeoContext()
@@ -13,10 +23,38 @@
     }
     if (seo) {
         seo.title = 'Basic Cache | Examples | Memory Cache'
-        seo.description = 'Interactive demo of basic memory cache operations in TypeScript. Try get, set, and delete with a live visual cache state powered by @humanspeak/memory-cache.'
+        seo.description =
+            'Interactive demo of basic memory cache operations in TypeScript. Try get, set, and delete with a live visual cache state powered by @humanspeak/memory-cache.'
+        seo.ogTitle = 'Basic Cache'
+        seo.ogTagline = 'Try get, set, and delete with a live cache state'
+        seo.ogFeatures = ['Set Values', 'Get Values', 'Delete Keys', 'Live State']
+        seo.ogSlug = 'examples-basic-cache'
     }
 </script>
 
-<Example title="Basic Cache">
+{#snippet defaultCode()}
+    <CodeReferenceV2
+        samples={[
+            {
+                id: 'basic-cache-default',
+                label: 'Default.svelte',
+                ...manifest['basic-cache/demos/Default.svelte']
+            }
+        ]}
+        columns={1}
+    />
+{/snippet}
+
+<ExampleV2
+    figId="FIG-001"
+    tag="CACHE"
+    title={{ prefix: 'basic ', accent: 'cache', end: '.' }}
+    description="Try `get`, `set`, and `delete` against a live `MemoryCache` instance and watch the cache state update."
+    sheetLabel="SHEET 01 / 01"
+    barCells={[{ k: 'pattern', v: 'basic operations' }]}
+    sourceUrl={`${SOURCE_URL}basic-cache/demos/Default.svelte`}
+    codeSnippet={defaultCode}
+    codeLabel="show code"
+>
     <BasicCache />
-</Example>
+</ExampleV2>
diff --git a/docs/src/routes/examples/cache-statistics/+page.svelte b/docs/src/routes/examples/cache-statistics/+page.svelte
index a4380ca..f25a161 100644
--- a/docs/src/routes/examples/cache-statistics/+page.svelte
+++ b/docs/src/routes/examples/cache-statistics/+page.svelte
@@ -1,7 +1,17 @@
 <script lang="ts">
-    import { getBreadcrumbContext, getSeoContext } from '@humanspeak/docs-kit'
-    import Example from '$lib/components/general/Example.svelte'
-    import CacheStatistics from '$lib/examples/CacheStatistics.svelte'
+    import {
+        CodeReferenceV2,
+        type DemoManifestEntry,
+        ExampleV2,
+        getBreadcrumbContext,
+        getSeoContext
+    } from '@humanspeak/docs-kit'
+    import CacheStatistics from '$lib/examples/cache-statistics/demos/Default.svelte'
+    import demoManifest from '$lib/demo-manifest.json'
+
+    const SOURCE_URL =
+        'https://github.com/humanspeak/memory-cache/blob/main/docs/src/lib/examples/'
+    const manifest = demoManifest as Record<string, DemoManifestEntry>
 
     const breadcrumbs = getBreadcrumbContext()
     const seo = getSeoContext()
@@ -13,10 +23,38 @@
     }
     if (seo) {
         seo.title = 'Cache Statistics | Examples | Memory Cache'
-        seo.description = 'Monitor cache hit rate, miss rate, and overall performance in real-time. Interactive demo of built-in statistics tracking in @humanspeak/memory-cache.'
+        seo.description =
+            'Monitor cache hit rate, miss rate, and overall performance in real-time. Interactive demo of built-in statistics tracking in @humanspeak/memory-cache.'
+        seo.ogTitle = 'Cache Statistics'
+        seo.ogTagline = 'Monitor cache hit rate, miss rate, and performance'
+        seo.ogFeatures = ['Hit Rate', 'Miss Rate', 'Evictions', 'Live Metrics']
+        seo.ogSlug = 'examples-cache-statistics'
     }
 </script>
 
-<Example title="Cache Statistics">
+{#snippet defaultCode()}
+    <CodeReferenceV2
+        samples={[
+            {
+                id: 'cache-statistics-default',
+                label: 'Default.svelte',
+                ...manifest['cache-statistics/demos/Default.svelte']
+            }
+        ]}
+        columns={1}
+    />
+{/snippet}
+
+<ExampleV2
+    figId="FIG-001"
+    tag="METRICS"
+    title={{ prefix: 'cache ', accent: 'statistics', end: '.' }}
+    description="Monitor hit rate, miss rate, evictions, and cache size as operations run against a live cache."
+    sheetLabel="SHEET 01 / 01"
+    barCells={[{ k: 'pattern', v: 'live metrics' }]}
+    sourceUrl={`${SOURCE_URL}cache-statistics/demos/Default.svelte`}
+    codeSnippet={defaultCode}
+    codeLabel="show code"
+>
     <CacheStatistics />
-</Example>
+</ExampleV2>
diff --git a/docs/src/routes/examples/lru-eviction/+page.svelte b/docs/src/routes/examples/lru-eviction/+page.svelte
index c5da541..a0584cd 100644
--- a/docs/src/routes/examples/lru-eviction/+page.svelte
+++ b/docs/src/routes/examples/lru-eviction/+page.svelte
@@ -1,7 +1,17 @@
 <script lang="ts">
-    import { getBreadcrumbContext, getSeoContext } from '@humanspeak/docs-kit'
-    import Example from '$lib/components/general/Example.svelte'
-    import LruEviction from '$lib/examples/LruEviction.svelte'
+    import {
+        CodeReferenceV2,
+        type DemoManifestEntry,
+        ExampleV2,
+        getBreadcrumbContext,
+        getSeoContext
+    } from '@humanspeak/docs-kit'
+    import LruEviction from '$lib/examples/lru-eviction/demos/Default.svelte'
+    import demoManifest from '$lib/demo-manifest.json'
+
+    const SOURCE_URL =
+        'https://github.com/humanspeak/memory-cache/blob/main/docs/src/lib/examples/'
+    const manifest = demoManifest as Record<string, DemoManifestEntry>
 
     const breadcrumbs = getBreadcrumbContext()
     const seo = getSeoContext()
@@ -13,10 +23,38 @@
     }
     if (seo) {
         seo.title = 'LRU Eviction | Examples | Memory Cache'
-        seo.description = 'See how least recently used items are evicted when the cache reaches capacity. Interactive demo of LRU eviction in @humanspeak/memory-cache for TypeScript.'
+        seo.description =
+            'See how least recently used items are evicted when the cache reaches capacity. Interactive demo of LRU eviction in @humanspeak/memory-cache for TypeScript.'
+        seo.ogTitle = 'LRU Eviction'
+        seo.ogTagline = 'Watch least recently used entries leave the cache'
+        seo.ogFeatures = ['Max Size', 'Access Order', 'Eviction', 'Live State']
+        seo.ogSlug = 'examples-lru-eviction'
     }
 </script>
 
-<Example title="LRU Eviction">
+{#snippet defaultCode()}
+    <CodeReferenceV2
+        samples={[
+            {
+                id: 'lru-eviction-default',
+                label: 'Default.svelte',
+                ...manifest['lru-eviction/demos/Default.svelte']
+            }
+        ]}
+        columns={1}
+    />
+{/snippet}
+
+<ExampleV2
+    figId="FIG-001"
+    tag="EVICTION"
+    title={{ prefix: 'lru ', accent: 'eviction', end: '.' }}
+    description="Fill a bounded cache and watch the least recently used entry get evicted when capacity is reached."
+    sheetLabel="SHEET 01 / 01"
+    barCells={[{ k: 'pattern', v: 'least recently used' }]}
+    sourceUrl={`${SOURCE_URL}lru-eviction/demos/Default.svelte`}
+    codeSnippet={defaultCode}
+    codeLabel="show code"
+>
     <LruEviction />
-</Example>
+</ExampleV2>
diff --git a/docs/src/routes/examples/ttl-expiration/+page.svelte b/docs/src/routes/examples/ttl-expiration/+page.svelte
index 60ac6a4..2de4245 100644
--- a/docs/src/routes/examples/ttl-expiration/+page.svelte
+++ b/docs/src/routes/examples/ttl-expiration/+page.svelte
@@ -1,7 +1,17 @@
 <script lang="ts">
-    import { getBreadcrumbContext, getSeoContext } from '@humanspeak/docs-kit'
-    import Example from '$lib/components/general/Example.svelte'
-    import TtlExpiration from '$lib/examples/TtlExpiration.svelte'
+    import {
+        CodeReferenceV2,
+        type DemoManifestEntry,
+        ExampleV2,
+        getBreadcrumbContext,
+        getSeoContext
+    } from '@humanspeak/docs-kit'
+    import TtlExpiration from '$lib/examples/ttl-expiration/demos/Default.svelte'
+    import demoManifest from '$lib/demo-manifest.json'
+
+    const SOURCE_URL =
+        'https://github.com/humanspeak/memory-cache/blob/main/docs/src/lib/examples/'
+    const manifest = demoManifest as Record<string, DemoManifestEntry>
 
     const breadcrumbs = getBreadcrumbContext()
     const seo = getSeoContext()
@@ -13,10 +23,38 @@
     }
     if (seo) {
         seo.title = 'TTL Expiration | Examples | Memory Cache'
-        seo.description = 'Watch cache entries expire in real-time with countdown timers. Explore how TTL-based expiration works in @humanspeak/memory-cache with this interactive demo.'
+        seo.description =
+            'Watch cache entries expire in real-time with countdown timers. Explore how TTL-based expiration works in @humanspeak/memory-cache with this interactive demo.'
+        seo.ogTitle = 'TTL Expiration'
+        seo.ogTagline = 'Watch cache entries expire in real time'
+        seo.ogFeatures = ['TTL', 'Countdowns', 'Expiration', 'Cleanup']
+        seo.ogSlug = 'examples-ttl-expiration'
     }
 </script>
 
-<Example title="TTL Expiration">
+{#snippet defaultCode()}
+    <CodeReferenceV2
+        samples={[
+            {
+                id: 'ttl-expiration-default',
+                label: 'Default.svelte',
+                ...manifest['ttl-expiration/demos/Default.svelte']
+            }
+        ]}
+        columns={1}
+    />
+{/snippet}
+
+<ExampleV2
+    figId="FIG-001"
+    tag="EXPIRATION"
+    title={{ prefix: 'ttl ', accent: 'expiration', end: '.' }}
+    description="Create short-lived entries and watch time-to-live expiration remove them from the cache."
+    sheetLabel="SHEET 01 / 01"
+    barCells={[{ k: 'pattern', v: 'time to live' }]}
+    sourceUrl={`${SOURCE_URL}ttl-expiration/demos/Default.svelte`}
+    codeSnippet={defaultCode}
+    codeLabel="show code"
+>
     <TtlExpiration />
-</Example>
+</ExampleV2>
diff --git a/docs/vite.config.ts b/docs/vite.config.ts
index da613f0..35d90db 100644
--- a/docs/vite.config.ts
+++ b/docs/vite.config.ts
@@ -1,9 +1,11 @@
 import {
+    demoManifestPlugin,
     docMirrorsPlugin,
     llmsFullPlugin,
     llmsPlugin,
     sitemapManifestPlugin
 } from '@humanspeak/docs-kit/vite'
+import { svelteMotionOptimize } from '@humanspeak/svelte-motion/vite'
 import { sveltekit } from '@sveltejs/kit/vite'
 import tailwindcss from '@tailwindcss/vite'
 import { defineConfig } from 'vite'
@@ -13,6 +15,7 @@ import { docsConfig } from './src/lib/docs-config'
 export default defineConfig({
     plugins: [
         sitemapManifestPlugin({ blogDir: false }),
+        demoManifestPlugin(),
         docMirrorsPlugin({ siteUrl: docsConfig.url }),
         llmsFullPlugin({
             siteUrl: docsConfig.url,
@@ -25,9 +28,20 @@ export default defineConfig({
             prepend: 'static/llms-prepend.md',
             append: 'static/llms-append.md'
         }),
+        svelteMotionOptimize(),
         tailwindcss(),
         sveltekit()
     ],
+    optimizeDeps: {
+        exclude: [
+            '@humanspeak/docs-kit',
+            '@humanspeak/svelte-motion',
+            '@humanspeak/svelte-satori-fix',
+            '@resvg/resvg-js',
+            'satori',
+            'satori-html'
+        ]
+    },
     server: {
         port: 8288
     }

From 5ff93891c129fa3fe30554dd14f88b2f8fdedf19 Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Tue, 2 Jun 2026 21:01:32 -0400
Subject: [PATCH 06/22] docs: update basic cache example shell

- Restyle the basic cache demo with the V2 example chrome
- Add miss-state telemetry and focused side-rail notes
---
 .../examples/basic-cache/demos/Default.svelte | 532 ++++++++++++++----
 .../routes/examples/basic-cache/+page.svelte  |  44 +-
 2 files changed, 467 insertions(+), 109 deletions(-)

diff --git a/docs/src/lib/examples/basic-cache/demos/Default.svelte b/docs/src/lib/examples/basic-cache/demos/Default.svelte
index 360f680..9c1fc7f 100644
--- a/docs/src/lib/examples/basic-cache/demos/Default.svelte
+++ b/docs/src/lib/examples/basic-cache/demos/Default.svelte
@@ -3,8 +3,10 @@
     import Trash2 from '@lucide/svelte/icons/trash-2'
     import { onMount } from 'svelte'
 
+    const capacity = 10
+
     // Create a cache instance
-    const cache = new MemoryCache<string>({ maxSize: 10 })
+    const cache = new MemoryCache<string>({ maxSize: capacity })
 
     // State
     let entries = $state<{ key: string; value: string }[]>([])
@@ -13,6 +15,16 @@
     let lastOperation = $state<{ type: string; key: string; result?: string | null } | null>(null)
     let getKey = $state('')
     let getResult = $state<string | null>(null)
+    let operationCount = $state(0)
+
+    let lastOperationLabel = $derived(lastOperation ? lastOperation.type.toLowerCase() : 'seeded')
+    let isLookupMiss = $derived(lastOperation?.type === 'GET' && getResult === null)
+    let lookupLabel = $derived(
+        lastOperation?.type === 'GET' ? (isLookupMiss ? 'miss' : 'hit') : 'idle'
+    )
+    let resultLabel = $derived(
+        lastOperation?.type === 'GET' ? (getResult ?? 'undefined (miss)') : 'waiting'
+    )
 
     function updateEntries() {
         entries = cache.keys().map((key) => ({
@@ -25,6 +37,7 @@
         if (!inputKey.trim()) return
         cache.set(inputKey, inputValue || `Value for ${inputKey}`)
         lastOperation = { type: 'SET', key: inputKey }
+        operationCount += 1
         updateEntries()
         inputKey = ''
         inputValue = ''
@@ -35,11 +48,13 @@
         const result = cache.get(getKey)
         getResult = result ?? null
         lastOperation = { type: 'GET', key: getKey, result: result ?? 'undefined (miss)' }
+        operationCount += 1
     }
 
     function handleDelete(key: string) {
         cache.delete(key)
         lastOperation = { type: 'DELETE', key }
+        operationCount += 1
         updateEntries()
         if (getKey === key) getResult = null
     }
@@ -47,140 +62,404 @@
     function handleClear() {
         cache.clear()
         lastOperation = { type: 'CLEAR', key: 'all' }
+        operationCount += 1
         entries = []
         getResult = null
     }
 
-    // Seed some initial data on mount
-    onMount(() => {
+    function seedInitialData() {
+        cache.clear()
         cache.set('user:1', 'Alice')
         cache.set('user:2', 'Bob')
         cache.set('config', 'production')
         updateEntries()
+    }
+
+    function handleReset() {
+        seedInitialData()
+        inputKey = ''
+        inputValue = ''
+        getKey = ''
+        getResult = null
+        operationCount = 0
+        lastOperation = null
+    }
+
+    // Seed some initial data on mount
+    onMount(() => {
+        seedInitialData()
     })
 </script>
 
-<div class="flex w-full max-w-4xl flex-col gap-6 lg:flex-row">
-    <!-- Controls Panel -->
-    <div class="flex-1 rounded-xl border border-border bg-card p-6 shadow-sm">
-        <h3 class="mb-4 text-lg font-semibold text-foreground">Cache Operations</h3>
-
-        <!-- Set Operation -->
-        <div class="mb-6">
-            <span class="mb-2 block text-sm font-medium text-foreground">Set Value</span>
-            <div class="flex gap-2">
-                <input
-                    type="text"
-                    bind:value={inputKey}
-                    placeholder="Key"
-                    aria-label="Cache key"
-                    class="flex-1 rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus:border-brand-500 focus:outline-none"
-                />
-                <input
-                    type="text"
-                    bind:value={inputValue}
-                    placeholder="Value"
-                    aria-label="Cache value"
-                    class="flex-1 rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus:border-brand-500 focus:outline-none"
-                />
-                <button
-                    onclick={handleSet}
-                    class="rounded-md bg-brand-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-brand-700"
-                >
-                    Set
-                </button>
-            </div>
-        </div>
-
-        <!-- Get Operation -->
-        <div class="mb-6">
-            <label for="get-key-input" class="mb-2 block text-sm font-medium text-foreground">Get Value</label>
-            <div class="flex gap-2">
-                <input
-                    id="get-key-input"
-                    type="text"
-                    bind:value={getKey}
-                    placeholder="Key to retrieve"
-                    class="flex-1 rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus:border-brand-500 focus:outline-none"
-                />
-                <button
-                    onclick={handleGet}
-                    class="rounded-md bg-brand-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-brand-700"
-                >
-                    Get
-                </button>
+<div class="demo-shell">
+    <div class="demo-telemetry">
+        <div>items · <span>{entries.length}</span></div>
+        <div>capacity · <span>{capacity}</span></div>
+        <div>ops · <span>{operationCount}</span></div>
+        <div>last · <span>{lastOperationLabel}</span></div>
+        <div class:miss={isLookupMiss}>lookup · <span>{lookupLabel}</span></div>
+        <button type="button" onclick={handleReset}>reset</button>
+    </div>
+
+    <div class="demo-frame">
+        <section class="operation-panel" aria-label="Cache operations">
+            <div class="operation-row">
+                <div class="operation-label">
+                    <span>set</span>
+                    <p>write or update a key</p>
+                </div>
+                <div class="operation-controls set-controls">
+                    <input
+                        type="text"
+                        bind:value={inputKey}
+                        placeholder="key"
+                        aria-label="Cache key"
+                    />
+                    <input
+                        type="text"
+                        bind:value={inputValue}
+                        placeholder="value"
+                        aria-label="Cache value"
+                    />
+                    <button type="button" onclick={handleSet}>set</button>
+                </div>
             </div>
-            {#if getResult !== null}
-                <div class="mt-2 rounded-md bg-green-500/10 px-3 py-2 text-sm text-green-700 dark:text-green-400">
-                    Result: <code class="font-mono">{getResult}</code>
+
+            <div class="operation-row">
+                <div class="operation-label">
+                    <label for="get-key-input">get</label>
+                    <p>read without mutating state</p>
+                </div>
+                <div class="operation-controls get-controls">
+                    <input
+                        id="get-key-input"
+                        type="text"
+                        bind:value={getKey}
+                        placeholder="key"
+                    />
+                    <button type="button" onclick={handleGet}>get</button>
                 </div>
-            {/if}
-        </div>
-
-        <!-- Clear -->
-        <button
-            onclick={handleClear}
-            class="rounded-md border border-red-500/50 px-4 py-2 text-sm font-medium text-red-600 transition-colors hover:bg-red-500/10"
-        >
-            Clear All
-        </button>
-
-        <!-- Last Operation -->
-        {#if lastOperation}
-            <div class="mt-4 rounded-md bg-muted/50 px-3 py-2 text-sm">
-                <span class="font-medium text-brand-600">{lastOperation.type}</span>
-                <span class="text-muted-foreground"> → </span>
-                <code class="font-mono text-foreground">{lastOperation.key}</code>
-                {#if lastOperation.result}
-                    <span class="text-muted-foreground"> = </span>
-                    <code class="font-mono text-foreground">{lastOperation.result}</code>
-                {/if}
             </div>
-        {/if}
-    </div>
 
-    <!-- Cache State Panel -->
-    <div class="flex-1 rounded-xl border border-border bg-card p-6 shadow-sm">
-        <div class="mb-4 flex items-center justify-between">
-            <h3 class="text-lg font-semibold text-foreground">Cache State</h3>
-            <span class="rounded-full bg-brand-500/10 px-2.5 py-1 text-xs font-medium text-brand-600">
-                {entries.length} items
-            </span>
-        </div>
-
-        {#if entries.length === 0}
-            <div class="flex h-48 items-center justify-center text-muted-foreground">
-                Cache is empty
+            <div class="result-row" class:miss={isLookupMiss}>
+                <div>result · <span>{resultLabel}</span></div>
+                <button type="button" onclick={handleClear}>clear all</button>
+            </div>
+
+        </section>
+
+        <section class="cache-panel" aria-label="Cache state">
+            <div class="cache-head">
+                <div>key</div>
+                <div>value</div>
+                <div>action</div>
             </div>
-        {:else}
-            <div class="space-y-2">
-                {#each entries as entry (entry.key)}
-                    <div class="cache-entry flex items-center justify-between rounded-lg border border-border bg-background p-3">
-                        <div class="min-w-0 flex-1">
-                            <div class="truncate font-mono text-sm font-medium text-foreground">
-                                {entry.key}
-                            </div>
-                            <div class="truncate font-mono text-xs text-muted-foreground">
-                                {entry.value}
-                            </div>
+
+            {#if entries.length === 0}
+                <div class="empty-state">
+                    <span>cache empty</span>
+                    <p>set a key to populate the in-memory store</p>
+                </div>
+            {:else}
+                {#each entries as entry, index (entry.key)}
+                    <div class="cache-entry">
+                        <div>
+                            <span>{String(index + 1).padStart(2, '0')}</span>
+                            <code>{entry.key}</code>
                         </div>
+                        <code>{entry.value}</code>
                         <button
+                            type="button"
                             onclick={() => handleDelete(entry.key)}
-                            class="ml-2 flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-red-500/10 hover:text-red-600"
                             title="Delete entry"
+                            aria-label={`Delete ${entry.key}`}
                         >
-                            <Trash2 size={12} />
+                            <Trash2 size={13} />
                         </button>
                     </div>
                 {/each}
-            </div>
-        {/if}
+            {/if}
+        </section>
+    </div>
+
+    <div class="demo-foot">
+        <div>store · <span>memory</span></div>
+        <div>eviction · <span>lru ready</span></div>
+        <div>ttl · <span>none</span></div>
+        <div>keys · <span>{entries.length}</span></div>
+        <div>mode · <span>live</span></div>
     </div>
 </div>
 
 <style>
+    .demo-shell {
+        display: flex;
+        min-height: 560px;
+        width: 100%;
+        flex-direction: column;
+        background: var(--brut-bg);
+        color: var(--brut-ink);
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+    }
+
+    .demo-telemetry,
+    .demo-foot {
+        display: grid;
+        background: var(--brut-bg-2);
+        color: var(--brut-ink-3);
+        font-size: 11px;
+    }
+
+    .demo-telemetry {
+        grid-template-columns: repeat(6, minmax(0, 1fr));
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .demo-foot {
+        grid-template-columns: repeat(5, minmax(0, 1fr));
+        border-top: 1px solid var(--brut-rule);
+    }
+
+    .demo-telemetry div,
+    .demo-telemetry button,
+    .demo-foot div {
+        min-width: 0;
+        border-right: 1px solid var(--brut-rule);
+        padding: 8px 14px;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    .demo-telemetry button {
+        border: 0;
+        border-right: 1px solid var(--brut-rule);
+        background: transparent;
+        color: var(--brut-accent);
+        font: inherit;
+        text-align: left;
+        cursor: pointer;
+    }
+
+    .demo-telemetry span,
+    .demo-foot span {
+        color: var(--brut-ink);
+    }
+
+    .demo-telemetry .miss,
+    .demo-telemetry .miss span {
+        color: #dc2626;
+    }
+
+    .demo-frame {
+        display: grid;
+        min-height: 0;
+        flex: 1;
+        grid-template-columns: minmax(300px, 0.8fr) minmax(360px, 1.2fr);
+        background: var(--brut-bg);
+    }
+
+    .operation-panel {
+        display: flex;
+        min-width: 0;
+        flex-direction: column;
+        border-right: 1px solid var(--brut-rule);
+        background: color-mix(in srgb, var(--brut-bg-2) 58%, var(--brut-bg));
+    }
+
+    .operation-row {
+        display: grid;
+        grid-template-columns: 120px minmax(0, 1fr);
+        gap: 16px;
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 18px 22px;
+    }
+
+    .operation-label span,
+    .operation-label label {
+        display: block;
+        margin-bottom: 6px;
+        color: var(--brut-ink);
+        font-size: 13px;
+        font-weight: 700;
+        text-transform: uppercase;
+    }
+
+    .operation-label p {
+        margin: 0;
+        color: var(--brut-ink-3);
+        font-size: 11px;
+        line-height: 1.45;
+    }
+
+    .operation-controls {
+        display: grid;
+        min-width: 0;
+        gap: 8px;
+    }
+
+    .set-controls {
+        grid-template-columns: minmax(0, 1fr) minmax(0, 1fr) auto;
+    }
+
+    .get-controls {
+        grid-template-columns: minmax(0, 1fr) auto;
+    }
+
+    input,
+    button {
+        border-radius: 0;
+        font: inherit;
+    }
+
+    input {
+        min-width: 0;
+        border: 1px solid var(--brut-rule);
+        background: var(--brut-bg);
+        color: var(--brut-ink);
+        padding: 9px 10px;
+        font-size: 12px;
+        outline: none;
+    }
+
+    input::placeholder {
+        color: var(--brut-ink-3);
+    }
+
+    input:focus {
+        border-color: var(--brut-accent);
+    }
+
+    .operation-controls button,
+    .result-row button {
+        border: 1px solid var(--brut-rule);
+        background: var(--brut-bg);
+        color: var(--brut-accent);
+        padding: 9px 12px;
+        font-size: 12px;
+        cursor: pointer;
+    }
+
+    .operation-controls button:hover,
+    .result-row button:hover,
+    .demo-telemetry button:hover,
+    .cache-entry button:hover {
+        background: color-mix(in srgb, var(--brut-accent) 12%, transparent);
+    }
+
+    .result-row {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 12px;
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 14px 22px;
+        color: var(--brut-ink-3);
+        font-size: 11px;
+    }
+
+    .result-row span {
+        color: var(--brut-ink);
+    }
+
+    .result-row.miss {
+        background: color-mix(in srgb, #dc2626 9%, transparent);
+        color: #b91c1c;
+    }
+
+    .result-row.miss span {
+        color: #dc2626;
+    }
+
+    .cache-panel {
+        min-width: 0;
+        background: var(--brut-bg);
+    }
+
+    .cache-head,
     .cache-entry {
-        animation: slideIn 0.2s ease-out;
+        display: grid;
+        grid-template-columns: minmax(180px, 0.9fr) minmax(180px, 1fr) 72px;
+        align-items: center;
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .cache-head {
+        background: var(--brut-bg-2);
+        color: var(--brut-ink-3);
+        font-size: 11px;
+        text-transform: uppercase;
+    }
+
+    .cache-head div,
+    .cache-entry > div,
+    .cache-entry > code,
+    .cache-entry > button {
+        min-width: 0;
+        border-right: 1px solid var(--brut-rule);
+        padding: 12px 14px;
+    }
+
+    .cache-entry {
+        min-height: 58px;
+        color: var(--brut-ink);
+        font-size: 12px;
+        animation: slideIn 0.18s ease-out;
+    }
+
+    .cache-entry:nth-child(even) {
+        background: color-mix(in srgb, var(--brut-bg-2) 42%, var(--brut-bg));
+    }
+
+    .cache-entry > div {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+    }
+
+    .cache-entry span {
+        color: var(--brut-ink-3);
+        font-size: 11px;
+    }
+
+    .cache-entry code {
+        overflow: hidden;
+        color: var(--brut-ink);
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    .cache-entry button {
+        display: grid;
+        height: 100%;
+        place-items: center;
+        border: 0;
+        border-right: 1px solid var(--brut-rule);
+        background: transparent;
+        color: var(--brut-ink-3);
+        cursor: pointer;
+    }
+
+    .empty-state {
+        display: grid;
+        min-height: 260px;
+        place-content: center;
+        gap: 8px;
+        padding: 32px;
+        text-align: center;
+    }
+
+    .empty-state span {
+        color: var(--brut-ink);
+        font-size: 14px;
+        font-weight: 700;
+        text-transform: uppercase;
+    }
+
+    .empty-state p {
+        margin: 0;
+        color: var(--brut-ink-3);
+        font-size: 12px;
     }
 
     @keyframes slideIn {
@@ -193,4 +472,45 @@
             transform: translateX(0);
         }
     }
+
+    @media (max-width: 900px) {
+        .demo-telemetry,
+        .demo-foot {
+            grid-template-columns: repeat(2, minmax(0, 1fr));
+        }
+
+        .demo-frame {
+            grid-template-columns: 1fr;
+        }
+
+        .operation-panel {
+            border-right: 0;
+            border-bottom: 1px solid var(--brut-rule);
+        }
+    }
+
+    @media (max-width: 640px) {
+        .operation-row,
+        .set-controls,
+        .get-controls,
+        .cache-head,
+        .cache-entry {
+            grid-template-columns: 1fr;
+        }
+
+        .cache-head {
+            display: none;
+        }
+
+        .cache-entry > div,
+        .cache-entry > code,
+        .cache-entry > button {
+            border-right: 0;
+        }
+
+        .cache-entry > button {
+            justify-content: start;
+            border-top: 1px solid var(--brut-rule);
+        }
+    }
 </style>
diff --git a/docs/src/routes/examples/basic-cache/+page.svelte b/docs/src/routes/examples/basic-cache/+page.svelte
index d4bb3bf..f1c4bde 100644
--- a/docs/src/routes/examples/basic-cache/+page.svelte
+++ b/docs/src/routes/examples/basic-cache/+page.svelte
@@ -6,6 +6,10 @@
         getBreadcrumbContext,
         getSeoContext
     } from '@humanspeak/docs-kit'
+    import ArrowLeftRight from '@lucide/svelte/icons/arrow-left-right'
+    import RotateCcw from '@lucide/svelte/icons/rotate-ccw'
+    import SearchX from '@lucide/svelte/icons/search-x'
+    import Sparkles from '@lucide/svelte/icons/sparkles'
     import BasicCache from '$lib/examples/basic-cache/demos/Default.svelte'
     import demoManifest from '$lib/demo-manifest.json'
 
@@ -45,16 +49,50 @@
     />
 {/snippet}
 
+{#snippet cacheNotes()}
+    <ul>
+        <li>
+            <Sparkles />
+            <span>
+                The demo starts with <code>user:1</code>, <code>user:2</code>, and
+                <code>config</code>, then mirrors every operation into the live table.
+            </span>
+        </li>
+        <li>
+            <ArrowLeftRight />
+            <span>
+                <code>set(key, value)</code> writes a value; <code>get(key)</code>
+                returns the cached value without changing the store.
+            </span>
+        </li>
+        <li>
+            <SearchX />
+            <span>
+                A missing <code>get</code> returns <code>undefined</code> and marks
+                the <code>lookup</code> telemetry plus <code>result</code> row red.
+            </span>
+        </li>
+        <li>
+            <RotateCcw />
+            <span>
+                Use <code>delete</code>, <code>clear()</code>, and <code>reset</code>
+                to compare one-key removal, an empty cache, and the seeded baseline.
+            </span>
+        </li>
+    </ul>
+{/snippet}
+
 <ExampleV2
     figId="FIG-001"
-    tag="CACHE"
-    title={{ prefix: 'basic ', accent: 'cache', end: '.' }}
-    description="Try `get`, `set`, and `delete` against a live `MemoryCache` instance and watch the cache state update."
+    tag="CACHE-BASICS"
+    title={{ prefix: 'set + get with ', accent: 'memorycache', end: '.' }}
+    description="Create a `MemoryCache` and drive the core `set`, `get`, and `delete` methods against live state."
     sheetLabel="SHEET 01 / 01"
     barCells={[{ k: 'pattern', v: 'basic operations' }]}
     sourceUrl={`${SOURCE_URL}basic-cache/demos/Default.svelte`}
     codeSnippet={defaultCode}
     codeLabel="show code"
+    notes={cacheNotes}
 >
     <BasicCache />
 </ExampleV2>

From b1782fb97dd632c6f2b45a48568d0c5a8c4a8c57 Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Tue, 2 Jun 2026 21:21:47 -0400
Subject: [PATCH 07/22] docs: update cache statistics example shell

- Restyle the statistics demo with the V2 example chrome
- Keep the event log scroll-contained inside the demo panel
---
 .../cache-statistics/demos/Default.svelte     | 647 +++++++++++++-----
 .../examples/cache-statistics/+page.svelte    |  45 +-
 2 files changed, 515 insertions(+), 177 deletions(-)

diff --git a/docs/src/lib/examples/cache-statistics/demos/Default.svelte b/docs/src/lib/examples/cache-statistics/demos/Default.svelte
index c476d96..7885193 100644
--- a/docs/src/lib/examples/cache-statistics/demos/Default.svelte
+++ b/docs/src/lib/examples/cache-statistics/demos/Default.svelte
@@ -1,95 +1,105 @@
 <script lang="ts">
-    import { MemoryCache, type OnSetContext, type OnHitContext, type OnMissContext, type OnDeleteContext, type OnEvictContext } from '@humanspeak/memory-cache'
+    import {
+        MemoryCache,
+        type OnDeleteContext,
+        type OnEvictContext,
+        type OnHitContext,
+        type OnMissContext,
+        type OnSetContext
+    } from '@humanspeak/memory-cache'
     import RotateCcw from '@lucide/svelte/icons/rotate-ccw'
     import Zap from '@lucide/svelte/icons/zap'
     import { onMount } from 'svelte'
 
-    // Statistics
+    const capacity = 5
+    const ttl = 30_000
+
+    type OperationType = 'SET' | 'HIT' | 'MISS' | 'DELETE' | 'EVICT'
+    type Operation = { type: OperationType; key: string; timestamp: number }
+
     let hits = $state(0)
     let misses = $state(0)
     let sets = $state(0)
     let deletes = $state(0)
     let evictions = $state(0)
+    let operationLog = $state<Operation[]>([])
+    let cache = $state<MemoryCache<string> | null>(null)
+    let tick = $state(0)
 
-    let hitRate = $derived(hits + misses > 0 ? (hits / (hits + misses)) * 100 : 0)
-
-    // Operation log
-    let operationLog = $state<{ type: string; key: string; timestamp: number }[]>([])
+    let requests = $derived(hits + misses)
+    let totalOperations = $derived(hits + misses + sets + deletes + evictions)
+    let hitRate = $derived(requests > 0 ? (hits / requests) * 100 : 0)
+    let cacheSize = $derived(cache?.size() ?? 0)
+    let recentOperation = $derived(operationLog[0]?.type.toLowerCase() ?? 'seeded')
 
-    function logOperation(type: string, key: string) {
+    function logOperation(type: OperationType, key: string) {
         operationLog = [{ type, key, timestamp: Date.now() }, ...operationLog.slice(0, 19)]
     }
 
-    // Create cache with hooks for monitoring
-    let cache = $state<MemoryCache<string> | null>(null)
-
     function initCache() {
         cache = new MemoryCache<string>({
-            maxSize: 5,
-            ttl: 30000,
+            maxSize: capacity,
+            ttl,
             hooks: {
                 onSet: (ctx: OnSetContext<string>) => {
-                    sets++
+                    sets += 1
                     logOperation('SET', ctx.key)
                 },
                 onHit: (ctx: OnHitContext<string>) => {
-                    hits++
+                    hits += 1
                     logOperation('HIT', ctx.key)
                 },
                 onMiss: (ctx: OnMissContext) => {
-                    misses++
+                    misses += 1
                     logOperation('MISS', ctx.key)
                 },
                 onDelete: (ctx: OnDeleteContext<string>) => {
-                    deletes++
+                    deletes += 1
                     logOperation('DELETE', ctx.key)
                 },
                 onEvict: (ctx: OnEvictContext<string>) => {
-                    evictions++
+                    evictions += 1
                     logOperation('EVICT', ctx.key)
                 }
             }
         })
 
-        // Seed some data (these will trigger onSet)
         cache.set('user:1', 'Alice')
         cache.set('user:2', 'Bob')
         cache.set('config', 'production')
     }
 
-    // Test operations
     function simulateHit() {
         if (!cache) return
         const keys = cache.keys()
-        if (keys.length > 0) {
-            const key = keys[Math.floor(Math.random() * keys.length)]
-            cache.get(key)
-        }
+        if (!keys.length) return
+
+        const key = keys[Math.floor(Math.random() * keys.length)]
+        cache.get(key)
     }
 
     function simulateMiss() {
-        if (!cache) return
-        cache.get(`nonexistent:${Date.now()}`)
+        cache?.get(`missing:${Date.now().toString(36)}`)
     }
 
     function simulateSet() {
         if (!cache) return
-        const id = Math.random().toString(36).substring(2, 6)
-        cache.set(`item:${id}`, `Value ${id}`)
+
+        const id = Math.random().toString(36).slice(2, 6)
+        cache.set(`item:${id}`, `value ${id}`)
     }
 
     function simulateDelete() {
         if (!cache) return
+
         const keys = cache.keys()
-        if (keys.length > 0) {
-            cache.delete(keys[0])
-        }
+        if (keys.length) cache.delete(keys[0])
     }
 
     function simulateBurst() {
         if (!cache) return
-        // Simulate realistic traffic pattern
-        for (let i = 0; i < 10; i++) {
+
+        for (let i = 0; i < 10; i += 1) {
             setTimeout(() => {
                 const rand = Math.random()
                 if (rand < 0.6) simulateHit()
@@ -110,188 +120,441 @@
         initCache()
     }
 
-    function getOperationColor(type: string): string {
-        switch (type) {
-            case 'HIT': return 'text-green-600 bg-green-500/10'
-            case 'MISS': return 'text-red-600 bg-red-500/10'
-            case 'SET': return 'text-blue-600 bg-blue-500/10'
-            case 'DELETE': return 'text-orange-600 bg-orange-500/10'
-            case 'EVICT': return 'text-purple-600 bg-purple-500/10'
-            default: return 'text-muted-foreground bg-muted'
-        }
-    }
-
     function formatTime(timestamp: number): string {
         const seconds = Math.floor((Date.now() - timestamp) / 1000)
-        if (seconds < 1) return 'just now'
-        if (seconds < 60) return `${seconds}s ago`
-        return `${Math.floor(seconds / 60)}m ago`
+        if (seconds < 1) return 'now'
+        if (seconds < 60) return `${seconds}s`
+        return `${Math.floor(seconds / 60)}m`
+    }
+
+    function operationClass(type: OperationType): string {
+        return `op-${type.toLowerCase()}`
     }
 
-    // Initialize once on mount
     onMount(() => {
         initCache()
     })
 
-    // Update timestamps every second
-    let tick = $state(0)
     $effect(() => {
-        const interval = setInterval(() => tick++, 1000)
+        const interval = setInterval(() => {
+            tick += 1
+        }, 1000)
+
         return () => clearInterval(interval)
     })
 </script>
 
-<div class="flex w-full max-w-5xl flex-col gap-6">
-    <!-- Stats Cards -->
-    <div class="grid grid-cols-2 gap-4 md:grid-cols-5">
-        <div class="rounded-xl border border-border bg-card p-4 text-center shadow-sm">
-            <div class="text-2xl font-bold text-green-600">{hits}</div>
-            <div class="text-sm text-muted-foreground">Hits</div>
-        </div>
-        <div class="rounded-xl border border-border bg-card p-4 text-center shadow-sm">
-            <div class="text-2xl font-bold text-red-600">{misses}</div>
-            <div class="text-sm text-muted-foreground">Misses</div>
-        </div>
-        <div class="rounded-xl border border-border bg-card p-4 text-center shadow-sm">
-            <div class="text-2xl font-bold text-blue-600">{sets}</div>
-            <div class="text-sm text-muted-foreground">Sets</div>
-        </div>
-        <div class="rounded-xl border border-border bg-card p-4 text-center shadow-sm">
-            <div class="text-2xl font-bold text-orange-600">{deletes}</div>
-            <div class="text-sm text-muted-foreground">Deletes</div>
-        </div>
-        <div class="rounded-xl border border-border bg-card p-4 text-center shadow-sm">
-            <div class="text-2xl font-bold text-purple-600">{evictions}</div>
-            <div class="text-sm text-muted-foreground">Evictions</div>
-        </div>
+<div class="demo-shell">
+    <div class="demo-telemetry">
+        <div>requests · <span>{requests}</span></div>
+        <div>hit rate · <span>{hitRate.toFixed(1)}%</span></div>
+        <div>size · <span>{cacheSize}/{capacity}</span></div>
+        <div>ttl · <span>{ttl / 1000}s</span></div>
+        <div>last · <span>{recentOperation}</span></div>
+        <button type="button" onclick={resetStats}>reset</button>
     </div>
 
-    <div class="flex flex-col gap-6 lg:flex-row">
-        <!-- Hit Rate Panel -->
-        <div class="flex-1 rounded-xl border border-border bg-card p-6 shadow-sm">
-            <h3 class="mb-4 text-lg font-semibold text-foreground">Hit Rate</h3>
-
-            <!-- Circular progress -->
-            <div class="mb-6 flex justify-center">
-                <div class="relative h-32 w-32">
-                    <svg class="h-full w-full -rotate-90" viewBox="0 0 100 100">
-                        <!-- Background circle -->
-                        <circle
-                            cx="50" cy="50" r="40"
-                            fill="none"
-                            stroke="currentColor"
-                            stroke-width="8"
-                            class="text-muted"
-                        />
-                        <!-- Progress circle -->
-                        <circle
-                            cx="50" cy="50" r="40"
-                            fill="none"
-                            stroke="currentColor"
-                            stroke-width="8"
-                            stroke-linecap="round"
-                            stroke-dasharray="{hitRate * 2.51327} 251.327"
-                            class="transition-all duration-300"
-                            class:text-green-500={hitRate >= 70}
-                            class:text-yellow-500={hitRate >= 40 && hitRate < 70}
-                            class:text-red-500={hitRate < 40}
-                        />
-                    </svg>
-                    <div class="absolute inset-0 flex items-center justify-center">
-                        <span class="text-2xl font-bold text-foreground">{hitRate.toFixed(1)}%</span>
-                    </div>
+    <div class="demo-frame">
+        <section class="metrics-panel" aria-label="Cache statistics">
+            <div class="rate-band">
+                <div class="rate-copy">
+                    <span>hit rate</span>
+                    <strong>{hitRate.toFixed(1)}%</strong>
+                    <p>{hits} hits / {requests} reads</p>
+                </div>
+                <div
+                    class="rate-meter"
+                    aria-label="Hit rate meter"
+                    style={`--rate: ${hitRate.toFixed(1)}%`}
+                >
+                    <span></span>
                 </div>
             </div>
 
-            <div class="text-center text-sm text-muted-foreground">
-                {hits} hits / {hits + misses} total requests
-            </div>
-
-            <!-- Control buttons -->
-            <div class="mt-6 grid grid-cols-2 gap-2">
-                <button
-                    onclick={simulateHit}
-                    class="rounded-md bg-green-600 px-3 py-2 text-sm font-medium text-white transition-colors hover:bg-green-700"
-                >
-                    Simulate Hit
-                </button>
-                <button
-                    onclick={simulateMiss}
-                    class="rounded-md bg-red-600 px-3 py-2 text-sm font-medium text-white transition-colors hover:bg-red-700"
-                >
-                    Simulate Miss
-                </button>
-                <button
-                    onclick={simulateSet}
-                    class="rounded-md bg-blue-600 px-3 py-2 text-sm font-medium text-white transition-colors hover:bg-blue-700"
-                >
-                    Set Entry
-                </button>
-                <button
-                    onclick={simulateDelete}
-                    class="rounded-md bg-orange-600 px-3 py-2 text-sm font-medium text-white transition-colors hover:bg-orange-700"
-                >
-                    Delete Entry
-                </button>
+            <div class="metric-grid">
+                <div class="metric hit">
+                    <span>hits</span>
+                    <strong>{hits}</strong>
+                </div>
+                <div class="metric miss">
+                    <span>misses</span>
+                    <strong>{misses}</strong>
+                </div>
+                <div class="metric set">
+                    <span>sets</span>
+                    <strong>{sets}</strong>
+                </div>
+                <div class="metric delete">
+                    <span>deletes</span>
+                    <strong>{deletes}</strong>
+                </div>
+                <div class="metric evict">
+                    <span>evictions</span>
+                    <strong>{evictions}</strong>
+                </div>
+                <div class="metric total">
+                    <span>ops</span>
+                    <strong>{totalOperations}</strong>
+                </div>
             </div>
 
-            <div class="mt-4 flex gap-2">
-                <button
-                    onclick={simulateBurst}
-                    class="flex-1 rounded-md border border-brand-500 px-3 py-2 text-sm font-medium text-brand-600 transition-colors hover:bg-brand-500/10"
-                >
-                    <Zap size={14} class="mr-1 inline" />
-                    Burst (10 ops)
+            <div class="control-grid">
+                <button type="button" onclick={simulateHit}>hit</button>
+                <button type="button" onclick={simulateMiss}>miss</button>
+                <button type="button" onclick={simulateSet}>set</button>
+                <button type="button" onclick={simulateDelete}>delete</button>
+                <button type="button" class="burst" onclick={simulateBurst}>
+                    <Zap size={13} />
+                    burst
                 </button>
-                <button
-                    onclick={resetStats}
-                    class="rounded-md border border-border px-3 py-2 text-sm font-medium text-foreground transition-colors hover:border-brand-500/50"
-                    title="Reset statistics"
-                >
-                    <RotateCcw size={14} />
+                <button type="button" class="icon" onclick={resetStats} title="Reset statistics">
+                    <RotateCcw size={13} />
                 </button>
             </div>
-        </div>
+        </section>
 
-        <!-- Operation Log -->
-        <div class="flex-1 rounded-xl border border-border bg-card p-6 shadow-sm">
-            <div class="mb-4 flex items-center justify-between">
-                <h3 class="text-lg font-semibold text-foreground">Operation Log</h3>
-                <span class="text-xs text-muted-foreground">Last 20 operations</span>
+        <section class="log-panel" aria-label="Operation log">
+            <div class="log-head">
+                <div>event</div>
+                <div>key</div>
+                <div>age</div>
             </div>
 
-            {#if operationLog.length === 0}
-                <div class="flex h-64 items-center justify-center text-muted-foreground">
-                    No operations yet
-                </div>
-            {:else}
-                <div class="max-h-80 space-y-1.5 overflow-y-auto">
-                    {#each operationLog as op, i (op.timestamp + i)}
-                        <div class="log-entry flex items-center justify-between rounded-md border border-border bg-background px-3 py-2">
-                            <div class="flex items-center gap-2">
-                                <span class="rounded px-2 py-0.5 text-xs font-bold {getOperationColor(op.type)}">
-                                    {op.type}
-                                </span>
-                                <code class="font-mono text-sm text-foreground">{op.key}</code>
-                            </div>
-                            <span class="text-xs text-muted-foreground">
+            <div class="log-list">
+                {#if operationLog.length === 0}
+                    <div class="empty-state">
+                        <span>no operations</span>
+                        <p>run traffic to populate the hook log</p>
+                    </div>
+                {:else}
+                    {#each operationLog as op, index (op.timestamp + index)}
+                        <div class={`log-entry ${operationClass(op.type)}`}>
+                            <div>{op.type}</div>
+                            <code>{op.key}</code>
+                            <span>
                                 {#key tick}
                                     {formatTime(op.timestamp)}
                                 {/key}
                             </span>
                         </div>
                     {/each}
-                </div>
-            {/if}
-        </div>
+                {/if}
+            </div>
+        </section>
+    </div>
+
+    <div class="demo-foot">
+        <div>hooks · <span>set hit miss delete evict</span></div>
+        <div>capacity · <span>{capacity}</span></div>
+        <div>entries · <span>{cacheSize}</span></div>
+        <div>events · <span>{operationLog.length}</span></div>
+        <div>mode · <span>live</span></div>
     </div>
 </div>
 
 <style>
+    .demo-shell {
+        display: flex;
+        height: 560px;
+        width: 100%;
+        flex-direction: column;
+        background: var(--brut-bg);
+        color: var(--brut-ink);
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+    }
+
+    .demo-telemetry,
+    .demo-foot {
+        display: grid;
+        background: var(--brut-bg-2);
+        color: var(--brut-ink-3);
+        font-size: 11px;
+    }
+
+    .demo-telemetry {
+        grid-template-columns: repeat(6, minmax(0, 1fr));
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .demo-foot {
+        grid-template-columns: repeat(5, minmax(0, 1fr));
+        border-top: 1px solid var(--brut-rule);
+    }
+
+    .demo-telemetry div,
+    .demo-telemetry button,
+    .demo-foot div {
+        min-width: 0;
+        border-right: 1px solid var(--brut-rule);
+        padding: 8px 14px;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    .demo-telemetry button {
+        border: 0;
+        border-right: 1px solid var(--brut-rule);
+        background: transparent;
+        color: var(--brut-accent);
+        font: inherit;
+        text-align: left;
+        cursor: pointer;
+    }
+
+    .demo-telemetry span,
+    .demo-foot span {
+        color: var(--brut-ink);
+    }
+
+    .demo-frame {
+        display: grid;
+        min-height: 0;
+        flex: 1;
+        grid-template-columns: minmax(320px, 0.9fr) minmax(380px, 1.1fr);
+        background: var(--brut-bg);
+    }
+
+    .metrics-panel {
+        display: flex;
+        min-width: 0;
+        min-height: 0;
+        flex-direction: column;
+        border-right: 1px solid var(--brut-rule);
+        background: color-mix(in srgb, var(--brut-bg-2) 58%, var(--brut-bg));
+    }
+
+    .rate-band {
+        display: grid;
+        grid-template-columns: minmax(0, 0.8fr) minmax(120px, 0.5fr);
+        gap: 20px;
+        align-items: end;
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 24px 22px;
+    }
+
+    .rate-copy span {
+        color: var(--brut-accent);
+        font-size: 11px;
+        text-transform: uppercase;
+    }
+
+    .rate-copy strong {
+        display: block;
+        margin-top: 10px;
+        color: var(--brut-ink);
+        font-size: 42px;
+        line-height: 0.95;
+    }
+
+    .rate-copy p {
+        margin: 10px 0 0;
+        color: var(--brut-ink-3);
+        font-size: 11px;
+    }
+
+    .rate-meter {
+        display: flex;
+        height: 96px;
+        align-items: end;
+        border: 1px solid var(--brut-rule);
+        background: var(--brut-bg);
+        padding: 6px;
+    }
+
+    .rate-meter span {
+        display: block;
+        width: 100%;
+        height: var(--rate);
+        min-height: 3px;
+        background: var(--brut-accent);
+        transition: height 0.2s ease;
+    }
+
+    .metric-grid {
+        display: grid;
+        grid-template-columns: repeat(3, minmax(0, 1fr));
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .metric {
+        min-width: 0;
+        border-right: 1px solid var(--brut-rule);
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 16px 18px;
+    }
+
+    .metric span {
+        display: block;
+        color: var(--brut-ink-3);
+        font-size: 11px;
+        text-transform: uppercase;
+    }
+
+    .metric strong {
+        display: block;
+        margin-top: 10px;
+        color: var(--brut-ink);
+        font-size: 26px;
+        line-height: 1;
+    }
+
+    .metric.hit strong {
+        color: #15803d;
+    }
+
+    .metric.miss strong {
+        color: #dc2626;
+    }
+
+    .metric.set strong {
+        color: #2563eb;
+    }
+
+    .metric.delete strong {
+        color: #c2410c;
+    }
+
+    .metric.evict strong {
+        color: #7c3aed;
+    }
+
+    .control-grid {
+        display: grid;
+        margin-top: auto;
+        grid-template-columns: repeat(3, minmax(0, 1fr));
+        border-top: 1px solid var(--brut-rule);
+    }
+
+    .control-grid button {
+        display: inline-flex;
+        min-height: 46px;
+        align-items: center;
+        justify-content: center;
+        gap: 6px;
+        border: 0;
+        border-right: 1px solid var(--brut-rule);
+        border-bottom: 1px solid var(--brut-rule);
+        border-radius: 0;
+        background: var(--brut-bg);
+        color: var(--brut-accent);
+        font: inherit;
+        font-size: 12px;
+        cursor: pointer;
+    }
+
+    .control-grid button:hover {
+        background: color-mix(in srgb, var(--brut-accent) 12%, transparent);
+    }
+
+    .control-grid .burst {
+        grid-column: span 2;
+    }
+
+    .log-panel {
+        display: flex;
+        min-width: 0;
+        min-height: 0;
+        flex-direction: column;
+        background: var(--brut-bg);
+    }
+
+    .log-list {
+        min-height: 0;
+        flex: 1;
+        overflow-y: auto;
+        overscroll-behavior: contain;
+    }
+
+    .log-head,
     .log-entry {
+        display: grid;
+        grid-template-columns: 108px minmax(180px, 1fr) 80px;
+        align-items: center;
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .log-head {
+        background: var(--brut-bg-2);
+        color: var(--brut-ink-3);
+        font-size: 11px;
+        text-transform: uppercase;
+    }
+
+    .log-head div,
+    .log-entry div,
+    .log-entry code,
+    .log-entry span {
+        min-width: 0;
+        border-right: 1px solid var(--brut-rule);
+        padding: 12px 14px;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    .log-entry {
+        min-height: 48px;
+        color: var(--brut-ink);
+        font-size: 12px;
         animation: slideIn 0.15s ease-out;
     }
 
+    .log-entry:nth-child(even) {
+        background: color-mix(in srgb, var(--brut-bg-2) 42%, var(--brut-bg));
+    }
+
+    .log-entry div {
+        color: var(--brut-accent);
+        font-weight: 700;
+    }
+
+    .log-entry.op-hit div {
+        color: #15803d;
+    }
+
+    .log-entry.op-miss div {
+        color: #dc2626;
+    }
+
+    .log-entry.op-set div {
+        color: #2563eb;
+    }
+
+    .log-entry.op-delete div {
+        color: #c2410c;
+    }
+
+    .log-entry.op-evict div {
+        color: #7c3aed;
+    }
+
+    .log-entry span {
+        color: var(--brut-ink-3);
+    }
+
+    .empty-state {
+        display: grid;
+        min-height: 320px;
+        place-content: center;
+        gap: 8px;
+        padding: 32px;
+        text-align: center;
+    }
+
+    .empty-state span {
+        color: var(--brut-ink);
+        font-size: 14px;
+        font-weight: 700;
+        text-transform: uppercase;
+    }
+
+    .empty-state p {
+        margin: 0;
+        color: var(--brut-ink-3);
+        font-size: 12px;
+    }
+
     @keyframes slideIn {
         from {
             opacity: 0;
@@ -302,4 +565,40 @@
             transform: translateX(0);
         }
     }
+
+    @media (max-width: 900px) {
+        .demo-telemetry,
+        .demo-foot {
+            grid-template-columns: repeat(2, minmax(0, 1fr));
+        }
+
+        .demo-frame {
+            grid-template-columns: 1fr;
+        }
+
+        .metrics-panel {
+            border-right: 0;
+            border-bottom: 1px solid var(--brut-rule);
+        }
+    }
+
+    @media (max-width: 640px) {
+        .rate-band,
+        .metric-grid,
+        .control-grid,
+        .log-head,
+        .log-entry {
+            grid-template-columns: 1fr;
+        }
+
+        .log-head {
+            display: none;
+        }
+
+        .log-entry div,
+        .log-entry code,
+        .log-entry span {
+            border-right: 0;
+        }
+    }
 </style>
diff --git a/docs/src/routes/examples/cache-statistics/+page.svelte b/docs/src/routes/examples/cache-statistics/+page.svelte
index f25a161..7db46ed 100644
--- a/docs/src/routes/examples/cache-statistics/+page.svelte
+++ b/docs/src/routes/examples/cache-statistics/+page.svelte
@@ -6,6 +6,10 @@
         getBreadcrumbContext,
         getSeoContext
     } from '@humanspeak/docs-kit'
+    import Activity from '@lucide/svelte/icons/activity'
+    import Gauge from '@lucide/svelte/icons/gauge'
+    import ListRestart from '@lucide/svelte/icons/list-restart'
+    import Zap from '@lucide/svelte/icons/zap'
     import CacheStatistics from '$lib/examples/cache-statistics/demos/Default.svelte'
     import demoManifest from '$lib/demo-manifest.json'
 
@@ -45,16 +49,51 @@
     />
 {/snippet}
 
+{#snippet statisticsNotes()}
+    <ul>
+        <li>
+            <Activity />
+            <span>
+                The cache wires <code>hooks</code> for <code>onHit</code>,
+                <code>onMiss</code>, <code>onSet</code>, <code>onDelete</code>,
+                and <code>onEvict</code>.
+            </span>
+        </li>
+        <li>
+            <Gauge />
+            <span>
+                The <code>hit rate</code> is calculated from reads only:
+                <code>hits / (hits + misses)</code>.
+            </span>
+        </li>
+        <li>
+            <Zap />
+            <span>
+                <code>burst</code> runs ten mixed operations so the event stream
+                can show hits, misses, writes, deletes, and evictions together.
+            </span>
+        </li>
+        <li>
+            <ListRestart />
+            <span>
+                <code>reset</code> clears the counters and creates a fresh cache
+                with <code>maxSize: 5</code> and a <code>30s</code> TTL.
+            </span>
+        </li>
+    </ul>
+{/snippet}
+
 <ExampleV2
     figId="FIG-001"
-    tag="METRICS"
-    title={{ prefix: 'cache ', accent: 'statistics', end: '.' }}
-    description="Monitor hit rate, miss rate, evictions, and cache size as operations run against a live cache."
+    tag="OBSERVABILITY"
+    title={{ prefix: 'watch cache ', accent: 'hooks', end: '.' }}
+    description="Measure `hit`, `miss`, `set`, `delete`, and `evict` events as live traffic moves through a `MemoryCache`."
     sheetLabel="SHEET 01 / 01"
     barCells={[{ k: 'pattern', v: 'live metrics' }]}
     sourceUrl={`${SOURCE_URL}cache-statistics/demos/Default.svelte`}
     codeSnippet={defaultCode}
     codeLabel="show code"
+    notes={statisticsNotes}
 >
     <CacheStatistics />
 </ExampleV2>

From 72f107a8aa00ba68e0b8c002529942a7398a17e2 Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 07:02:50 -0400
Subject: [PATCH 08/22] docs: update lru eviction example shell

- Restyle the LRU demo with the V2 example chrome
- Keep eviction history scroll-contained inside the demo panel
---
 .../lru-eviction/demos/Default.svelte         | 668 +++++++++++++-----
 .../routes/examples/lru-eviction/+page.svelte |  44 +-
 2 files changed, 537 insertions(+), 175 deletions(-)

diff --git a/docs/src/lib/examples/lru-eviction/demos/Default.svelte b/docs/src/lib/examples/lru-eviction/demos/Default.svelte
index dea9120..ac64145 100644
--- a/docs/src/lib/examples/lru-eviction/demos/Default.svelte
+++ b/docs/src/lib/examples/lru-eviction/demos/Default.svelte
@@ -1,14 +1,10 @@
 <script lang="ts">
     import { MemoryCache } from '@humanspeak/memory-cache'
-    import Lightbulb from '@lucide/svelte/icons/lightbulb'
     import MousePointer from '@lucide/svelte/icons/mouse-pointer'
     import Plus from '@lucide/svelte/icons/plus'
     import RotateCcw from '@lucide/svelte/icons/rotate-ccw'
-    import { onMount } from 'svelte'
 
-    // Create a small cache to demonstrate LRU eviction
-    let maxSize = $state(5)
-    let cache = $state(new MemoryCache<string>({ maxSize: maxSize }))
+    const defaultMaxSize = 5
 
     type EntryDisplay = {
         key: string
@@ -16,91 +12,108 @@
         accessOrder: number
     }
 
-    let entries = $state<EntryDisplay[]>([])
+    const initialCache = createSeededCache(defaultMaxSize)
+
+    let maxSize = $state(defaultMaxSize)
+    let cache = $state(initialCache)
+    let entries = $state(readEntries(initialCache))
     let evictionLog = $state<string[]>([])
-    let nextId = $state(1)
+    let nextId = $state(4)
     let accessCounter = $state(0)
 
-    function updateEntries() {
-        // Use entries() to read values without affecting LRU order
-        const cacheEntries = cache.entries()
-        entries = cacheEntries.map(([key, value], index) => ({
+    let capacityRatio = $derived(entries.length / maxSize)
+    let lruKey = $derived(entries[0]?.key ?? 'none')
+    let mruKey = $derived(entries.at(-1)?.key ?? 'none')
+
+    function createCache(size: number) {
+        return new MemoryCache<string>({ maxSize: size })
+    }
+
+    function createSeededCache(size: number) {
+        const nextCache = createCache(size)
+        for (let i = 1; i <= 3; i += 1) {
+            nextCache.set(`item:${i}`, `value ${i}`)
+        }
+        return nextCache
+    }
+
+    function readEntries(nextCache: MemoryCache<string>) {
+        return nextCache.entries().map(([key, value], index) => ({
             key,
             value: value ?? '',
-            accessOrder: index // Lower = least recently used
+            accessOrder: index
         }))
     }
 
+    function updateEntries() {
+        entries = readEntries(cache)
+    }
+
     function addEntry() {
         const key = `item:${nextId}`
-        const value = `Value #${nextId}`
+        const value = `value ${nextId}`
 
-        // Check if this will cause eviction
         if (cache.size() >= maxSize) {
-            const lruKey = cache.keys()[0] // First key is LRU
-            evictionLog = [`Evicted "${lruKey}" (LRU)`, ...evictionLog.slice(0, 9)]
+            const nextEviction = cache.keys()[0]
+            evictionLog = [`${nextEviction} -> ${key}`, ...evictionLog.slice(0, 11)]
         }
 
         cache.set(key, value)
-        nextId++
+        nextId += 1
         updateEntries()
     }
 
     function accessEntry(key: string) {
-        cache.get(key) // This updates the access order
-        accessCounter++
+        cache.get(key)
+        accessCounter += 1
         updateEntries()
     }
 
     function resetCache() {
-        cache = new MemoryCache<string>({ maxSize })
-        entries = []
+        cache = createSeededCache(maxSize)
+        entries = readEntries(cache)
         evictionLog = []
-        nextId = 1
+        nextId = 4
         accessCounter = 0
-
-        // Seed initial data
-        for (let i = 1; i <= 3; i++) {
-            cache.set(`item:${i}`, `Value #${i}`)
-            nextId = i + 1
-        }
-        updateEntries()
     }
 
     function updateMaxSize() {
-        cache = new MemoryCache<string>({ maxSize })
+        cache = createCache(maxSize)
         resetCache()
     }
 
-    function getPositionClass(index: number, total: number): string {
-        if (index === 0) return 'bg-red-500/20 text-red-600'
-        if (index === total - 1) return 'bg-green-500/20 text-green-600'
-        return 'bg-yellow-500/20 text-yellow-600'
-    }
-
-    function getCapacityClass(current: number, max: number): string {
-        const ratio = current / max
-        if (ratio < 0.7) return 'bg-green-500'
-        if (current < max) return 'bg-yellow-500'
-        return 'bg-red-500'
-    }
-
-    // Initialize once on mount
-    onMount(() => {
-        resetCache()
-    })
 </script>
 
-<div class="flex w-full max-w-4xl flex-col gap-6 lg:flex-row">
-    <!-- Controls Panel -->
-    <div class="w-full rounded-xl border border-border bg-card p-6 shadow-sm lg:w-72">
-        <h3 class="mb-4 text-lg font-semibold text-foreground">LRU Settings</h3>
+<div class="demo-shell">
+    <div class="demo-telemetry">
+        <div>size · <span>{entries.length}/{maxSize}</span></div>
+        <div>lru · <span>{lruKey}</span></div>
+        <div>mru · <span>{mruKey}</span></div>
+        <div>accesses · <span>{accessCounter}</span></div>
+        <div>evictions · <span>{evictionLog.length}</span></div>
+        <button type="button" onclick={resetCache}>reset</button>
+    </div>
 
-        <div class="space-y-4">
-            <div>
-                <label for="max-size-slider" class="mb-1.5 block text-sm font-medium text-foreground">
-                    Max Size: {maxSize}
-                </label>
+    <div class="demo-frame">
+        <section class="control-panel" aria-label="LRU controls">
+            <div class="capacity-panel">
+                <div class="capacity-copy">
+                    <span>capacity</span>
+                    <strong>{entries.length}/{maxSize}</strong>
+                    <p>full cache evicts the least recently used key</p>
+                </div>
+                <div
+                    class="capacity-meter"
+                    aria-label="Capacity meter"
+                    style={`--capacity: ${(capacityRatio * 100).toFixed(1)}%`}
+                    class:full={entries.length >= maxSize}
+                >
+                    <span></span>
+                </div>
+            </div>
+
+            <div class="setting-row">
+                <label for="max-size-slider">max size · <span>{maxSize}</span></label>
                 <input
                     id="max-size-slider"
                     type="range"
@@ -108,149 +121,460 @@
                     onchange={updateMaxSize}
                     min="3"
                     max="10"
-                    class="w-full accent-brand-500"
                 />
-                <p class="mt-1 text-xs text-muted-foreground">
-                    Cache evicts LRU items when full
-                </p>
             </div>
 
-            <button
-                onclick={addEntry}
-                class="w-full rounded-md bg-brand-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-brand-700"
-            >
-                <Plus size={14} class="mr-2 inline" />
-                Add New Entry
-            </button>
-
-            <button
-                onclick={resetCache}
-                class="w-full rounded-md border border-border px-4 py-2 text-sm font-medium text-foreground transition-colors hover:border-brand-500/50"
-            >
-                <RotateCcw size={14} class="mr-2 inline" />
-                Reset Cache
-            </button>
-        </div>
-
-        <!-- Stats -->
-        <div class="mt-6 space-y-2 rounded-lg bg-muted/50 p-4 text-sm">
-            <div class="flex justify-between">
-                <span class="text-muted-foreground">Current size</span>
-                <span class="font-medium text-foreground">{entries.length} / {maxSize}</span>
-            </div>
-            <div class="flex justify-between">
-                <span class="text-muted-foreground">Total accesses</span>
-                <span class="font-medium text-foreground">{accessCounter}</span>
-            </div>
-            <div class="flex justify-between">
-                <span class="text-muted-foreground">Total evictions</span>
-                <span class="font-medium text-red-600">{evictionLog.length}</span>
+            <div class="control-grid">
+                <button type="button" onclick={addEntry}>
+                    <Plus size={13} />
+                    add entry
+                </button>
+                <button type="button" onclick={resetCache}>
+                    <RotateCcw size={13} />
+                    reset
+                </button>
             </div>
-        </div>
-
-        <!-- Eviction Log -->
-        {#if evictionLog.length > 0}
-            <div class="mt-4">
-                <h4 class="mb-2 text-sm font-medium text-foreground">Eviction Log</h4>
-                <div class="max-h-32 space-y-1 overflow-y-auto text-xs">
-                    {#each evictionLog as log}
-                        <div class="rounded bg-red-500/10 px-2 py-1 text-red-600 dark:text-red-400">
-                            {log}
-                        </div>
-                    {/each}
+
+            <div class="eviction-panel">
+                <div class="eviction-head">
+                    <span>eviction log</span>
+                    <span>{evictionLog.length}</span>
                 </div>
-            </div>
-        {/if}
-    </div>
 
-    <!-- Cache Visualization -->
-    <div class="flex-1 rounded-xl border border-border bg-card p-6 shadow-sm">
-        <div class="mb-4">
-            <h3 class="text-lg font-semibold text-foreground">Cache Entries (LRU Order)</h3>
-            <p class="text-sm text-muted-foreground">
-                Click an entry to access it (moves to end). Top = Least Recently Used.
-            </p>
-        </div>
-
-        <!-- Capacity indicator -->
-        <div class="mb-4">
-            <div class="mb-1 flex justify-between text-xs">
-                <span class="text-muted-foreground">Capacity</span>
-                <span class="font-medium" class:text-red-500={entries.length === maxSize}>
-                    {entries.length}/{maxSize}
-                </span>
-            </div>
-            <div class="h-2 w-full overflow-hidden rounded-full bg-muted">
-                <div
-                    class="h-full transition-all duration-300 {getCapacityClass(entries.length, maxSize)}"
-                    style="width: {(entries.length / maxSize) * 100}%"
-                ></div>
+                <div class="eviction-list">
+                    {#if evictionLog.length === 0}
+                        <div class="empty-note">fill the cache, then add one more item</div>
+                    {:else}
+                        {#each evictionLog as log, index (`${log}-${index}`)}
+                            <div>{log}</div>
+                        {/each}
+                    {/if}
+                </div>
             </div>
-        </div>
+        </section>
 
-        {#if entries.length === 0}
-            <div class="flex h-48 items-center justify-center text-muted-foreground">
-                Cache is empty
+        <section class="cache-panel" aria-label="Cache entries in LRU order">
+            <div class="cache-head">
+                <div>rank</div>
+                <div>key</div>
+                <div>state</div>
             </div>
-        {:else}
-            <div class="space-y-2">
-                {#each entries as entry, index (entry.key)}
-                    <button
-                        onclick={() => accessEntry(entry.key)}
-                        class="lru-entry group flex w-full items-center justify-between rounded-lg border border-border bg-background p-3 text-left transition-all hover:border-brand-500/50 hover:shadow-sm"
-                    >
-                        <div class="flex items-center gap-3">
-                            <div
-                                class="flex h-8 w-8 items-center justify-center rounded-md text-xs font-bold {getPositionClass(index, entries.length)}"
-                            >
-                                {index + 1}
-                            </div>
+
+            <div class="entry-list">
+                {#if entries.length === 0}
+                    <div class="empty-state">
+                        <span>cache empty</span>
+                        <p>reset to seed the LRU list</p>
+                    </div>
+                {:else}
+                    {#each entries as entry, index (entry.key)}
+                        <button
+                            type="button"
+                            onclick={() => accessEntry(entry.key)}
+                            class="lru-entry"
+                            class:lru={index === 0}
+                            class:mru={index === entries.length - 1}
+                        >
                             <div>
-                                <div class="font-mono text-sm font-medium text-foreground">
-                                    {entry.key}
-                                </div>
-                                <div class="text-xs text-muted-foreground">
-                                    {entry.value}
-                                </div>
+                                <span>{String(index + 1).padStart(2, '0')}</span>
+                                <small>{index === 0 ? 'next out' : 'order'}</small>
                             </div>
-                        </div>
-                        <div class="flex items-center gap-2">
-                            {#if index === 0}
-                                <span class="rounded bg-red-500/10 px-2 py-0.5 text-xs font-medium text-red-600">
-                                    LRU (next eviction)
-                                </span>
-                            {:else if index === entries.length - 1}
-                                <span class="rounded bg-green-500/10 px-2 py-0.5 text-xs font-medium text-green-600">
+                            <code>
+                                <strong>{entry.key}</strong>
+                                <span>{entry.value}</span>
+                            </code>
+                            <div class="entry-state">
+                                {#if index === 0}
+                                    LRU
+                                {:else if index === entries.length - 1}
                                     MRU
-                                </span>
-                            {/if}
-                            <MousePointer size={14} class="text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100" />
-                        </div>
-                    </button>
-                {/each}
+                                {:else}
+                                    warm
+                                {/if}
+                                <MousePointer size={13} />
+                            </div>
+                        </button>
+                    {/each}
+                {/if}
             </div>
-        {/if}
+        </section>
+    </div>
 
-        <p class="mt-4 text-xs text-muted-foreground">
-            <Lightbulb size={14} class="mr-1 inline text-yellow-500" />
-            When the cache is full, adding a new entry evicts the LRU item (position #1).
-        </p>
+    <div class="demo-foot">
+        <div>policy · <span>least recently used</span></div>
+        <div>capacity · <span>{maxSize}</span></div>
+        <div>entries · <span>{entries.length}</span></div>
+        <div>next eviction · <span>{lruKey}</span></div>
+        <div>mode · <span>live</span></div>
     </div>
 </div>
 
 <style>
+    .demo-shell {
+        display: flex;
+        height: 560px;
+        width: 100%;
+        flex-direction: column;
+        background: var(--brut-bg);
+        color: var(--brut-ink);
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+    }
+
+    .demo-telemetry,
+    .demo-foot {
+        display: grid;
+        background: var(--brut-bg-2);
+        color: var(--brut-ink-3);
+        font-size: 11px;
+    }
+
+    .demo-telemetry {
+        grid-template-columns: repeat(6, minmax(0, 1fr));
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .demo-foot {
+        grid-template-columns: repeat(5, minmax(0, 1fr));
+        border-top: 1px solid var(--brut-rule);
+    }
+
+    .demo-telemetry div,
+    .demo-telemetry button,
+    .demo-foot div {
+        min-width: 0;
+        border-right: 1px solid var(--brut-rule);
+        padding: 8px 14px;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    .demo-telemetry button {
+        border: 0;
+        border-right: 1px solid var(--brut-rule);
+        background: transparent;
+        color: var(--brut-accent);
+        font: inherit;
+        text-align: left;
+        cursor: pointer;
+    }
+
+    .demo-telemetry span,
+    .demo-foot span {
+        color: var(--brut-ink);
+    }
+
+    .demo-frame {
+        display: grid;
+        min-height: 0;
+        flex: 1;
+        grid-template-columns: minmax(300px, 0.75fr) minmax(420px, 1.25fr);
+        background: var(--brut-bg);
+    }
+
+    .control-panel {
+        display: flex;
+        min-width: 0;
+        min-height: 0;
+        flex-direction: column;
+        border-right: 1px solid var(--brut-rule);
+        background: color-mix(in srgb, var(--brut-bg-2) 58%, var(--brut-bg));
+    }
+
+    .capacity-panel {
+        display: grid;
+        grid-template-columns: minmax(0, 0.8fr) minmax(110px, 0.45fr);
+        gap: 18px;
+        align-items: end;
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 24px 22px;
+    }
+
+    .capacity-copy span,
+    .eviction-head span:first-child,
+    .setting-row label {
+        color: var(--brut-accent);
+        font-size: 11px;
+        text-transform: uppercase;
+    }
+
+    .capacity-copy strong {
+        display: block;
+        margin-top: 10px;
+        color: var(--brut-ink);
+        font-size: 42px;
+        line-height: 0.95;
+    }
+
+    .capacity-copy p {
+        margin: 10px 0 0;
+        color: var(--brut-ink-3);
+        font-size: 11px;
+        line-height: 1.45;
+    }
+
+    .capacity-meter {
+        display: flex;
+        height: 96px;
+        align-items: end;
+        border: 1px solid var(--brut-rule);
+        background: var(--brut-bg);
+        padding: 6px;
+    }
+
+    .capacity-meter span {
+        display: block;
+        width: 100%;
+        height: var(--capacity);
+        min-height: 3px;
+        background: var(--brut-accent);
+        transition: height 0.2s ease;
+    }
+
+    .capacity-meter.full span {
+        background: #dc2626;
+    }
+
+    .setting-row {
+        display: grid;
+        gap: 12px;
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 18px 22px;
+    }
+
+    .setting-row label span {
+        color: var(--brut-ink);
+    }
+
+    input[type='range'] {
+        width: 100%;
+        accent-color: var(--brut-accent);
+    }
+
+    .control-grid {
+        display: grid;
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .control-grid button {
+        display: inline-flex;
+        min-height: 48px;
+        align-items: center;
+        justify-content: center;
+        gap: 6px;
+        border: 0;
+        border-right: 1px solid var(--brut-rule);
+        border-radius: 0;
+        background: var(--brut-bg);
+        color: var(--brut-accent);
+        font: inherit;
+        font-size: 12px;
+        cursor: pointer;
+    }
+
+    .control-grid button:hover,
+    .lru-entry:hover {
+        background: color-mix(in srgb, var(--brut-accent) 12%, transparent);
+    }
+
+    .eviction-panel {
+        display: flex;
+        min-height: 0;
+        flex: 1;
+        flex-direction: column;
+    }
+
+    .eviction-head {
+        display: flex;
+        justify-content: space-between;
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 12px 14px;
+    }
+
+    .eviction-head span:last-child {
+        color: var(--brut-ink);
+        font-size: 11px;
+    }
+
+    .eviction-list {
+        min-height: 0;
+        flex: 1;
+        overflow-y: auto;
+        overscroll-behavior: contain;
+    }
+
+    .eviction-list div,
+    .empty-note {
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 10px 14px;
+        color: #dc2626;
+        font-size: 11px;
+    }
+
+    .empty-note {
+        color: var(--brut-ink-3);
+    }
+
+    .cache-panel {
+        display: flex;
+        min-width: 0;
+        min-height: 0;
+        flex-direction: column;
+        background: var(--brut-bg);
+    }
+
+    .cache-head,
+    .lru-entry {
+        display: grid;
+        grid-template-columns: 120px minmax(180px, 1fr) 120px;
+        align-items: center;
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .cache-head {
+        background: var(--brut-bg-2);
+        color: var(--brut-ink-3);
+        font-size: 11px;
+        text-transform: uppercase;
+    }
+
+    .cache-head div,
+    .lru-entry > div,
+    .lru-entry > code {
+        min-width: 0;
+        border-right: 1px solid var(--brut-rule);
+        padding: 12px 14px;
+    }
+
+    .entry-list {
+        min-height: 0;
+        flex: 1;
+        overflow-y: auto;
+        overscroll-behavior: contain;
+    }
+
     .lru-entry {
-        animation: slideIn 0.2s ease-out;
+        width: 100%;
+        min-height: 68px;
+        border-top: 0;
+        border-right: 0;
+        border-left: 0;
+        border-radius: 0;
+        background: transparent;
+        color: var(--brut-ink);
+        font: inherit;
+        text-align: left;
+        cursor: pointer;
+        animation: slideIn 0.16s ease-out;
+    }
+
+    .lru-entry:nth-child(even) {
+        background: color-mix(in srgb, var(--brut-bg-2) 42%, var(--brut-bg));
+    }
+
+    .lru-entry.lru {
+        background: color-mix(in srgb, #dc2626 8%, var(--brut-bg));
+    }
+
+    .lru-entry.mru {
+        background: color-mix(in srgb, var(--brut-accent) 8%, var(--brut-bg));
+    }
+
+    .lru-entry span,
+    .lru-entry small {
+        display: block;
+        color: var(--brut-ink-3);
+        font-size: 11px;
+    }
+
+    .lru-entry code strong,
+    .lru-entry code span {
+        display: block;
+    }
+
+    .lru-entry code strong {
+        color: var(--brut-ink);
+        font-size: 13px;
+    }
+
+    .entry-state {
+        display: inline-flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 8px;
+        color: var(--brut-accent);
+        font-size: 12px;
+    }
+
+    .lru-entry.lru .entry-state {
+        color: #dc2626;
+    }
+
+    .empty-state {
+        display: grid;
+        min-height: 320px;
+        place-content: center;
+        gap: 8px;
+        padding: 32px;
+        text-align: center;
+    }
+
+    .empty-state span {
+        color: var(--brut-ink);
+        font-size: 14px;
+        font-weight: 700;
+        text-transform: uppercase;
+    }
+
+    .empty-state p {
+        margin: 0;
+        color: var(--brut-ink-3);
+        font-size: 12px;
     }
 
     @keyframes slideIn {
         from {
             opacity: 0;
-            transform: translateY(-4px);
+            transform: translateX(-8px);
         }
         to {
             opacity: 1;
-            transform: translateY(0);
+            transform: translateX(0);
+        }
+    }
+
+    @media (max-width: 900px) {
+        .demo-telemetry,
+        .demo-foot {
+            grid-template-columns: repeat(2, minmax(0, 1fr));
+        }
+
+        .demo-frame {
+            grid-template-columns: 1fr;
+        }
+
+        .control-panel {
+            border-right: 0;
+            border-bottom: 1px solid var(--brut-rule);
+        }
+    }
+
+    @media (max-width: 640px) {
+        .capacity-panel,
+        .control-grid,
+        .cache-head,
+        .lru-entry {
+            grid-template-columns: 1fr;
+        }
+
+        .cache-head {
+            display: none;
+        }
+
+        .lru-entry > div,
+        .lru-entry > code {
+            border-right: 0;
         }
     }
 </style>
diff --git a/docs/src/routes/examples/lru-eviction/+page.svelte b/docs/src/routes/examples/lru-eviction/+page.svelte
index a0584cd..6a4f766 100644
--- a/docs/src/routes/examples/lru-eviction/+page.svelte
+++ b/docs/src/routes/examples/lru-eviction/+page.svelte
@@ -6,6 +6,10 @@
         getBreadcrumbContext,
         getSeoContext
     } from '@humanspeak/docs-kit'
+    import Lightbulb from '@lucide/svelte/icons/lightbulb'
+    import MousePointer from '@lucide/svelte/icons/mouse-pointer'
+    import Plus from '@lucide/svelte/icons/plus'
+    import RotateCcw from '@lucide/svelte/icons/rotate-ccw'
     import LruEviction from '$lib/examples/lru-eviction/demos/Default.svelte'
     import demoManifest from '$lib/demo-manifest.json'
 
@@ -45,16 +49,50 @@
     />
 {/snippet}
 
+{#snippet lruNotes()}
+    <ul>
+        <li>
+            <Lightbulb />
+            <span>
+                LRU means <code>least recently used</code>: the oldest untouched
+                key is the first candidate when the cache reaches capacity.
+            </span>
+        </li>
+        <li>
+            <MousePointer />
+            <span>
+                Clicking an entry calls <code>get(key)</code>, moving that key to
+                the MRU end of the list.
+            </span>
+        </li>
+        <li>
+            <Plus />
+            <span>
+                <code>add entry</code> writes a new item. If <code>size === maxSize</code>,
+                the current LRU key is evicted before the new key lands.
+            </span>
+        </li>
+        <li>
+            <RotateCcw />
+            <span>
+                Changing <code>maxSize</code> resets the demo so capacity,
+                rank, and eviction behavior stay easy to compare.
+            </span>
+        </li>
+    </ul>
+{/snippet}
+
 <ExampleV2
     figId="FIG-001"
-    tag="EVICTION"
-    title={{ prefix: 'lru ', accent: 'eviction', end: '.' }}
-    description="Fill a bounded cache and watch the least recently used entry get evicted when capacity is reached."
+    tag="EVICTION-POLICY"
+    title={{ prefix: 'trace lru ', accent: 'eviction', end: '.' }}
+    description="Fill a bounded `MemoryCache`, access entries, and watch the least recently used key leave when capacity is reached."
     sheetLabel="SHEET 01 / 01"
     barCells={[{ k: 'pattern', v: 'least recently used' }]}
     sourceUrl={`${SOURCE_URL}lru-eviction/demos/Default.svelte`}
     codeSnippet={defaultCode}
     codeLabel="show code"
+    notes={lruNotes}
 >
     <LruEviction />
 </ExampleV2>

From b6d9c9c484b03524331671e94a03a4a23df1b99d Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 07:34:43 -0400
Subject: [PATCH 09/22] docs: update ttl expiration example shell

- Restyle the TTL demo with the V2 example chrome
- Add a spring-driven svelte-motion TTL meter
- Keep expiring entries scroll-contained inside the demo panel
---
 .../ttl-expiration/demos/Default.svelte       | 719 ++++++++++++++----
 .../examples/ttl-expiration/+page.svelte      |  44 +-
 2 files changed, 601 insertions(+), 162 deletions(-)

diff --git a/docs/src/lib/examples/ttl-expiration/demos/Default.svelte b/docs/src/lib/examples/ttl-expiration/demos/Default.svelte
index 640b582..1fbe047 100644
--- a/docs/src/lib/examples/ttl-expiration/demos/Default.svelte
+++ b/docs/src/lib/examples/ttl-expiration/demos/Default.svelte
@@ -1,17 +1,12 @@
 <script lang="ts">
     import { MemoryCache } from '@humanspeak/memory-cache'
+    import { motion, type MotionTransition } from '@humanspeak/svelte-motion'
     import Clock from '@lucide/svelte/icons/clock'
+    import Plus from '@lucide/svelte/icons/plus'
+    import RotateCcw from '@lucide/svelte/icons/rotate-ccw'
     import Shuffle from '@lucide/svelte/icons/shuffle'
-    import { onMount } from 'svelte'
 
     type CachedItem = { value: string; createdAt: number }
-
-    // State for custom TTL
-    let customTtl = $state(10)
-
-    // Create a new cache whenever TTL changes
-    let cache = $state(new MemoryCache<CachedItem>({ ttl: customTtl * 1000, maxSize: 20 }))
-
     type EntryDisplay = {
         key: string
         value: string
@@ -20,41 +15,81 @@
         remainingPercent: number
     }
 
-    let entries = $state<EntryDisplay[]>([])
+    const defaultTtl = 10
+    const maxSize = 20
+    const ttlSpring: MotionTransition = {
+        type: 'spring',
+        stiffness: 180,
+        damping: 24,
+        mass: 0.7
+    }
+
+    const initialCache = createSeededCache(defaultTtl)
+
+    let customTtl = $state(defaultTtl)
+    let cache = $state(initialCache)
+    let entries = $state(readEntries(initialCache, defaultTtl))
     let inputKey = $state('')
     let inputValue = $state('')
     let expiredCount = $state(0)
+    let additions = $state(3)
 
-    function updateEntries() {
+    let ttlMs = $derived(customTtl * 1000)
+    let shortestRemaining = $derived(
+        entries.length ? Math.min(...entries.map((entry) => entry.remainingMs)) : 0
+    )
+    let meterScale = $derived((entries[0]?.remainingPercent ?? 0) / 100)
+    let nextExpiration = $derived(entries[0]?.key ?? 'none')
+
+    function createCache(ttlSeconds: number) {
+        return new MemoryCache<CachedItem>({ ttl: ttlSeconds * 1000, maxSize })
+    }
+
+    function createSeededCache(ttlSeconds: number) {
         const now = Date.now()
-        const keys = cache.keys()
-        const ttlMs = customTtl * 1000
-
-        entries = keys.map((key) => {
-            const data = cache.get(key)
-            if (!data) return null
-
-            const elapsed = now - data.createdAt
-            const remainingMs = Math.max(0, ttlMs - elapsed)
-            const remainingPercent = (remainingMs / ttlMs) * 100
-
-            return {
-                key,
-                value: data.value,
-                createdAt: data.createdAt,
-                remainingMs,
-                remainingPercent
-            }
-        }).filter((e): e is EntryDisplay => e !== null && e.remainingMs > 0)
+        const nextCache = createCache(ttlSeconds)
+        nextCache.set('session:abc', { value: 'user session data', createdAt: now })
+        nextCache.set('token:xyz', { value: 'auth token', createdAt: now - 3000 })
+        nextCache.set('temp:123', { value: 'temporary data', createdAt: now - 7000 })
+        return nextCache
+    }
+
+    function readEntries(nextCache: MemoryCache<CachedItem>, ttlSeconds: number) {
+        const now = Date.now()
+        const nextTtlMs = ttlSeconds * 1000
+
+        return nextCache
+            .entries()
+            .map(([key, data]) => {
+                if (!data) return null
+
+                const elapsed = now - data.createdAt
+                const remainingMs = Math.max(0, nextTtlMs - elapsed)
+                const remainingPercent = (remainingMs / nextTtlMs) * 100
+
+                return {
+                    key,
+                    value: data.value,
+                    createdAt: data.createdAt,
+                    remainingMs,
+                    remainingPercent
+                }
+            })
+            .filter((entry): entry is EntryDisplay => entry !== null && entry.remainingMs > 0)
+            .sort((a, b) => a.remainingMs - b.remainingMs)
+    }
+
+    function updateEntries() {
+        entries = readEntries(cache, customTtl)
     }
 
     function handleAdd() {
         if (!inputKey.trim()) return
 
         const key = inputKey.trim()
-        const value = inputValue.trim() || `Value ${Date.now()}`
-
+        const value = inputValue.trim() || `value ${Date.now().toString(36)}`
         cache.set(key, { value, createdAt: Date.now() })
+        additions += 1
         updateEntries()
 
         inputKey = ''
@@ -62,42 +97,42 @@
     }
 
     function addRandomEntry() {
-        const id = Math.random().toString(36).substring(2, 8)
-        const key = `item:${id}`
-        cache.set(key, { value: `Random value ${id}`, createdAt: Date.now() })
+        const id = Math.random().toString(36).slice(2, 8)
+        cache.set(`item:${id}`, { value: `random ${id}`, createdAt: Date.now() })
+        additions += 1
         updateEntries()
     }
 
-    function formatTime(ms: number): string {
-        const seconds = Math.ceil(ms / 1000)
-        return `${seconds}s`
+    function resetCache() {
+        cache = createSeededCache(customTtl)
+        entries = readEntries(cache, customTtl)
+        expiredCount = 0
+        additions = 3
+        inputKey = ''
+        inputValue = ''
     }
 
-    function getProgressColor(percent: number): string {
-        if (percent > 60) return 'bg-green-500'
-        if (percent > 30) return 'bg-yellow-500'
-        return 'bg-red-500'
+    function updateTtl() {
+        resetCache()
     }
 
-    function updateTtl() {
-        // Recreate cache with new TTL
-        cache = new MemoryCache<CachedItem>({ ttl: customTtl * 1000, maxSize: 20 })
-        entries = []
-        expiredCount = 0
-        // Add initial entries
-        cache.set('session:abc', { value: 'User session data', createdAt: Date.now() })
-        cache.set('token:xyz', { value: 'Auth token', createdAt: Date.now() - 3000 })
-        updateEntries()
+    function formatTime(ms: number): string {
+        const seconds = Math.ceil(ms / 1000)
+        return `${seconds}s`
     }
 
-    // Update timer
-    let interval: ReturnType<typeof setInterval>
+    function expiryClass(percent: number): 'fresh' | 'warn' | 'danger' {
+        if (percent > 60) return 'fresh'
+        if (percent > 30) return 'warn'
+        return 'danger'
+    }
 
     $effect(() => {
-        interval = setInterval(() => {
+        const interval = setInterval(() => {
             const previousCount = entries.length
             updateEntries()
             const newCount = entries.length
+
             if (newCount < previousCount) {
                 expiredCount += previousCount - newCount
             }
@@ -105,48 +140,42 @@
 
         return () => clearInterval(interval)
     })
-
-    // Seed initial data on mount
-    onMount(() => {
-        cache.set('session:abc', { value: 'User session data', createdAt: Date.now() })
-        cache.set('token:xyz', { value: 'Auth token', createdAt: Date.now() - 3000 })
-        cache.set('temp:123', { value: 'Temporary data', createdAt: Date.now() - 7000 })
-        updateEntries()
-    })
 </script>
 
-<div class="flex w-full max-w-4xl flex-col gap-6 lg:flex-row">
-    <!-- Controls Panel -->
-    <div class="w-full rounded-xl border border-border bg-card p-6 shadow-sm lg:w-80">
-        <h3 class="mb-4 text-lg font-semibold text-foreground">Add Entry with TTL</h3>
-
-        <div class="space-y-4">
-            <div>
-                <label for="ttl-key" class="mb-1.5 block text-sm font-medium text-foreground">Key</label>
-                <input
-                    id="ttl-key"
-                    type="text"
-                    bind:value={inputKey}
-                    placeholder="cache:key"
-                    class="w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus:border-brand-500 focus:outline-none"
-                />
-            </div>
+<div class="demo-shell">
+    <div class="demo-telemetry">
+        <div>active · <span>{entries.length}</span></div>
+        <div>ttl · <span>{customTtl}s</span></div>
+        <div>next · <span>{nextExpiration}</span></div>
+        <div>remaining · <span>{shortestRemaining ? formatTime(shortestRemaining) : 'none'}</span></div>
+        <div>expired · <span>{expiredCount}</span></div>
+        <button type="button" onclick={resetCache}>reset</button>
+    </div>
 
-            <div>
-                <label for="ttl-value" class="mb-1.5 block text-sm font-medium text-foreground">Value</label>
-                <input
-                    id="ttl-value"
-                    type="text"
-                    bind:value={inputValue}
-                    placeholder="Optional value"
-                    class="w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus:border-brand-500 focus:outline-none"
-                />
+    <div class="demo-frame">
+        <section class="control-panel" aria-label="TTL controls">
+            <div class="ttl-panel">
+                <div class="ttl-copy">
+                    <span>time to live</span>
+                    <strong>{customTtl}s</strong>
+                    <p>entries disappear when their countdown reaches zero</p>
+                </div>
+                <div
+                    class="ttl-meter"
+                    aria-label="Next expiration meter"
+                    class:danger={entries[0] && entries[0].remainingPercent <= 30}
+                >
+                    <motion.div
+                        class="ttl-meter-fill"
+                        initial={false}
+                        animate={{ scaleY: meterScale }}
+                        transition={ttlSpring}
+                    />
+                </div>
             </div>
 
-            <div>
-                <label for="ttl-slider" class="mb-1.5 block text-sm font-medium text-foreground">
-                    TTL: {customTtl} seconds
-                </label>
+            <div class="setting-row">
+                <label for="ttl-slider">ttl · <span>{customTtl}s</span></label>
                 <input
                     id="ttl-slider"
                     type="range"
@@ -154,101 +183,473 @@
                     onchange={updateTtl}
                     min="3"
                     max="30"
-                    class="w-full accent-brand-500"
                 />
             </div>
 
-            <div class="flex gap-2">
-                <button
-                    onclick={handleAdd}
-                    class="flex-1 rounded-md bg-brand-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-brand-700"
-                >
-                    Add Entry
+            <div class="input-grid">
+                <input id="ttl-key" type="text" bind:value={inputKey} placeholder="key" />
+                <input id="ttl-value" type="text" bind:value={inputValue} placeholder="value" />
+            </div>
+
+            <div class="control-grid">
+                <button type="button" onclick={handleAdd}>
+                    <Plus size={13} />
+                    add
                 </button>
-                <button
-                    onclick={addRandomEntry}
-                    class="rounded-md border border-border px-3 py-2 text-sm font-medium text-foreground transition-colors hover:border-brand-500/50"
-                    title="Add random entry"
-                >
-                    <Shuffle size={14} />
+                <button type="button" onclick={addRandomEntry}>
+                    <Shuffle size={13} />
+                    random
+                </button>
+                <button type="button" onclick={resetCache}>
+                    <RotateCcw size={13} />
+                    reset
                 </button>
             </div>
-        </div>
 
-        <!-- Stats -->
-        <div class="mt-6 rounded-lg bg-muted/50 p-4">
-            <div class="flex justify-between text-sm">
-                <span class="text-muted-foreground">Active entries</span>
-                <span class="font-medium text-foreground">{entries.length}</span>
-            </div>
-            <div class="mt-2 flex justify-between text-sm">
-                <span class="text-muted-foreground">Expired (session)</span>
-                <span class="font-medium text-red-600">{expiredCount}</span>
+            <div class="stat-grid">
+                <div>
+                    <span>created</span>
+                    <strong>{additions}</strong>
+                </div>
+                <div>
+                    <span>expired</span>
+                    <strong>{expiredCount}</strong>
+                </div>
             </div>
-        </div>
-    </div>
+        </section>
 
-    <!-- Entries Panel -->
-    <div class="flex-1 rounded-xl border border-border bg-card p-6 shadow-sm">
-        <div class="mb-4 flex items-center justify-between">
-            <h3 class="text-lg font-semibold text-foreground">Cache Entries</h3>
-            <span class="text-xs text-muted-foreground">
-                Watch entries expire in real-time
-            </span>
-        </div>
-
-        {#if entries.length === 0}
-            <div class="flex h-64 flex-col items-center justify-center text-muted-foreground">
-                <Clock size={32} class="mb-3 text-muted-foreground/50" />
-                <p>No active entries</p>
-                <p class="text-sm">Add some entries to see TTL in action</p>
+        <section class="entries-panel" aria-label="TTL entries">
+            <div class="entry-head">
+                <div>key</div>
+                <div>value</div>
+                <div>ttl</div>
             </div>
-        {:else}
-            <div class="space-y-3">
-                {#each entries as entry (entry.key)}
-                    <div class="ttl-entry overflow-hidden rounded-lg border border-border bg-background">
-                        <div class="flex items-center justify-between p-3">
-                            <div class="min-w-0 flex-1">
-                                <div class="truncate font-mono text-sm font-medium text-foreground">
-                                    {entry.key}
-                                </div>
-                                <div class="truncate text-xs text-muted-foreground">
-                                    {entry.value}
-                                </div>
-                            </div>
-                            <div class="ml-3 text-right">
-                                <div class="text-lg font-bold tabular-nums" class:text-red-500={entry.remainingMs < 3000} class:text-yellow-500={entry.remainingMs >= 3000 && entry.remainingMs < 6000} class:text-green-500={entry.remainingMs >= 6000}>
-                                    {formatTime(entry.remainingMs)}
-                                </div>
+
+            <div class="entry-list">
+                {#if entries.length === 0}
+                    <div class="empty-state">
+                        <Clock size={22} />
+                        <span>no active entries</span>
+                        <p>add an entry or reset the cache</p>
+                    </div>
+                {:else}
+                    {#each entries as entry (entry.key)}
+                        <div class={`ttl-entry ${expiryClass(entry.remainingPercent)}`}>
+                            <code>
+                                <strong>{entry.key}</strong>
+                                <span>{new Date(entry.createdAt).toLocaleTimeString()}</span>
+                            </code>
+                            <div>{entry.value}</div>
+                            <div class="ttl-cell">
+                                <strong>{formatTime(entry.remainingMs)}</strong>
+                                <span style={`--remaining: ${entry.remainingPercent.toFixed(1)}%`}></span>
                             </div>
                         </div>
-                        <!-- Progress bar -->
-                        <div class="h-1 w-full bg-muted">
-                            <div
-                                class="h-full transition-all duration-100 {getProgressColor(entry.remainingPercent)}"
-                                style="width: {entry.remainingPercent}%"
-                            ></div>
-                        </div>
-                    </div>
-                {/each}
+                    {/each}
+                {/if}
             </div>
-        {/if}
+        </section>
+    </div>
+
+    <div class="demo-foot">
+        <div>policy · <span>time to live</span></div>
+        <div>ttl · <span>{customTtl}s</span></div>
+        <div>max size · <span>{maxSize}</span></div>
+        <div>entries · <span>{entries.length}</span></div>
+        <div>mode · <span>live</span></div>
     </div>
 </div>
 
 <style>
+    .demo-shell {
+        display: flex;
+        height: 560px;
+        width: 100%;
+        flex-direction: column;
+        background: var(--brut-bg);
+        color: var(--brut-ink);
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+    }
+
+    .demo-telemetry,
+    .demo-foot {
+        display: grid;
+        background: var(--brut-bg-2);
+        color: var(--brut-ink-3);
+        font-size: 11px;
+    }
+
+    .demo-telemetry {
+        grid-template-columns: repeat(6, minmax(0, 1fr));
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .demo-foot {
+        grid-template-columns: repeat(5, minmax(0, 1fr));
+        border-top: 1px solid var(--brut-rule);
+    }
+
+    .demo-telemetry div,
+    .demo-telemetry button,
+    .demo-foot div {
+        min-width: 0;
+        border-right: 1px solid var(--brut-rule);
+        padding: 8px 14px;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    .demo-telemetry button {
+        border: 0;
+        border-right: 1px solid var(--brut-rule);
+        background: transparent;
+        color: var(--brut-accent);
+        font: inherit;
+        text-align: left;
+        cursor: pointer;
+    }
+
+    .demo-telemetry span,
+    .demo-foot span {
+        color: var(--brut-ink);
+    }
+
+    .demo-frame {
+        display: grid;
+        min-height: 0;
+        flex: 1;
+        grid-template-columns: minmax(300px, 0.78fr) minmax(420px, 1.22fr);
+        background: var(--brut-bg);
+    }
+
+    .control-panel {
+        display: flex;
+        min-width: 0;
+        min-height: 0;
+        flex-direction: column;
+        border-right: 1px solid var(--brut-rule);
+        background: color-mix(in srgb, var(--brut-bg-2) 58%, var(--brut-bg));
+    }
+
+    .ttl-panel {
+        display: grid;
+        grid-template-columns: minmax(0, 0.8fr) minmax(110px, 0.45fr);
+        gap: 18px;
+        align-items: end;
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 24px 22px;
+    }
+
+    .ttl-copy span,
+    .setting-row label,
+    .stat-grid span {
+        color: var(--brut-accent);
+        font-size: 11px;
+        text-transform: uppercase;
+    }
+
+    .ttl-copy strong {
+        display: block;
+        margin-top: 10px;
+        color: var(--brut-ink);
+        font-size: 42px;
+        line-height: 0.95;
+    }
+
+    .ttl-copy p {
+        margin: 10px 0 0;
+        color: var(--brut-ink-3);
+        font-size: 11px;
+        line-height: 1.45;
+    }
+
+    .ttl-meter {
+        display: flex;
+        height: 96px;
+        align-items: end;
+        border: 1px solid var(--brut-rule);
+        background: var(--brut-bg);
+        padding: 6px;
+    }
+
+    .ttl-meter :global(.ttl-meter-fill) {
+        display: block;
+        width: 100%;
+        height: 100%;
+        min-height: 3px;
+        background: var(--brut-accent);
+        transform-origin: bottom;
+        will-change: transform;
+    }
+
+    .ttl-meter.danger :global(.ttl-meter-fill) {
+        background: #dc2626;
+    }
+
+    .setting-row,
+    .input-grid,
+    .control-grid,
+    .stat-grid {
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .setting-row {
+        display: grid;
+        gap: 12px;
+        padding: 18px 22px;
+    }
+
+    .setting-row label span {
+        color: var(--brut-ink);
+    }
+
+    input {
+        min-width: 0;
+        border: 1px solid var(--brut-rule);
+        border-radius: 0;
+        background: var(--brut-bg);
+        color: var(--brut-ink);
+        font: inherit;
+        font-size: 12px;
+        outline: none;
+    }
+
+    input[type='range'] {
+        width: 100%;
+        accent-color: var(--brut-accent);
+    }
+
+    input[type='text'] {
+        padding: 10px 12px;
+    }
+
+    input::placeholder {
+        color: var(--brut-ink-3);
+    }
+
+    input:focus {
+        border-color: var(--brut-accent);
+    }
+
+    .input-grid {
+        display: grid;
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+        gap: 8px;
+        padding: 14px 22px;
+    }
+
+    .control-grid,
+    .stat-grid {
+        display: grid;
+        grid-template-columns: repeat(3, minmax(0, 1fr));
+    }
+
+    .control-grid button {
+        display: inline-flex;
+        min-height: 48px;
+        align-items: center;
+        justify-content: center;
+        gap: 6px;
+        border: 0;
+        border-right: 1px solid var(--brut-rule);
+        border-radius: 0;
+        background: var(--brut-bg);
+        color: var(--brut-accent);
+        font: inherit;
+        font-size: 12px;
+        cursor: pointer;
+    }
+
+    .control-grid button:hover {
+        background: color-mix(in srgb, var(--brut-accent) 12%, transparent);
+    }
+
+    .stat-grid {
+        margin-top: auto;
+    }
+
+    .stat-grid div {
+        min-width: 0;
+        border-right: 1px solid var(--brut-rule);
+        padding: 14px 18px;
+    }
+
+    .stat-grid strong {
+        display: block;
+        margin-top: 8px;
+        color: var(--brut-ink);
+        font-size: 24px;
+    }
+
+    .entries-panel {
+        display: flex;
+        min-width: 0;
+        min-height: 0;
+        flex-direction: column;
+        background: var(--brut-bg);
+    }
+
+    .entry-head,
+    .ttl-entry {
+        display: grid;
+        grid-template-columns: minmax(180px, 0.9fr) minmax(180px, 1fr) 120px;
+        align-items: center;
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .entry-head {
+        background: var(--brut-bg-2);
+        color: var(--brut-ink-3);
+        font-size: 11px;
+        text-transform: uppercase;
+    }
+
+    .entry-head div,
+    .ttl-entry code,
+    .ttl-entry > div {
+        min-width: 0;
+        border-right: 1px solid var(--brut-rule);
+        padding: 12px 14px;
+    }
+
+    .entry-list {
+        min-height: 0;
+        flex: 1;
+        overflow-y: auto;
+        overscroll-behavior: contain;
+    }
+
     .ttl-entry {
-        animation: slideIn 0.2s ease-out;
+        min-height: 64px;
+        color: var(--brut-ink);
+        font-size: 12px;
+        animation: slideIn 0.16s ease-out;
+    }
+
+    .ttl-entry:nth-child(even) {
+        background: color-mix(in srgb, var(--brut-bg-2) 42%, var(--brut-bg));
+    }
+
+    .ttl-entry.warn {
+        background: color-mix(in srgb, #facc15 9%, var(--brut-bg));
+    }
+
+    .ttl-entry.danger {
+        background: color-mix(in srgb, #dc2626 8%, var(--brut-bg));
+    }
+
+    .ttl-entry code strong,
+    .ttl-entry code span {
+        display: block;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    .ttl-entry code strong {
+        color: var(--brut-ink);
+        font-size: 13px;
+    }
+
+    .ttl-entry code span {
+        color: var(--brut-ink-3);
+        font-size: 11px;
+    }
+
+    .ttl-cell strong {
+        display: block;
+        color: var(--brut-accent);
+        font-size: 18px;
+    }
+
+    .ttl-entry.warn .ttl-cell strong {
+        color: #ca8a04;
+    }
+
+    .ttl-entry.danger .ttl-cell strong {
+        color: #dc2626;
+    }
+
+    .ttl-cell span {
+        display: block;
+        height: 3px;
+        width: var(--remaining);
+        margin-top: 8px;
+        background: currentColor;
+    }
+
+    .empty-state {
+        display: grid;
+        min-height: 320px;
+        place-content: center;
+        gap: 8px;
+        padding: 32px;
+        color: var(--brut-ink-3);
+        text-align: center;
+    }
+
+    .empty-state :global(svg) {
+        margin: 0 auto 4px;
+        color: var(--brut-accent);
+    }
+
+    .empty-state span {
+        color: var(--brut-ink);
+        font-size: 14px;
+        font-weight: 700;
+        text-transform: uppercase;
+    }
+
+    .empty-state p {
+        margin: 0;
+        font-size: 12px;
     }
 
     @keyframes slideIn {
         from {
             opacity: 0;
-            transform: scale(0.95);
+            transform: translateX(-8px);
         }
         to {
             opacity: 1;
-            transform: scale(1);
+            transform: translateX(0);
+        }
+    }
+
+    @media (max-width: 900px) {
+        .demo-telemetry,
+        .demo-foot {
+            grid-template-columns: repeat(2, minmax(0, 1fr));
+        }
+
+        .demo-frame {
+            grid-template-columns: 1fr;
+        }
+
+        .control-panel {
+            border-right: 0;
+            border-bottom: 1px solid var(--brut-rule);
+        }
+    }
+
+    @media (max-width: 640px) {
+        .ttl-panel,
+        .input-grid,
+        .control-grid,
+        .stat-grid,
+        .entry-head,
+        .ttl-entry {
+            grid-template-columns: 1fr;
+        }
+
+        .entry-head {
+            display: none;
+        }
+
+        .ttl-entry code,
+        .ttl-entry > div {
+            border-right: 0;
         }
     }
 </style>
diff --git a/docs/src/routes/examples/ttl-expiration/+page.svelte b/docs/src/routes/examples/ttl-expiration/+page.svelte
index 2de4245..0279693 100644
--- a/docs/src/routes/examples/ttl-expiration/+page.svelte
+++ b/docs/src/routes/examples/ttl-expiration/+page.svelte
@@ -6,6 +6,10 @@
         getBreadcrumbContext,
         getSeoContext
     } from '@humanspeak/docs-kit'
+    import Clock from '@lucide/svelte/icons/clock'
+    import Hourglass from '@lucide/svelte/icons/hourglass'
+    import RotateCcw from '@lucide/svelte/icons/rotate-ccw'
+    import TimerOff from '@lucide/svelte/icons/timer-off'
     import TtlExpiration from '$lib/examples/ttl-expiration/demos/Default.svelte'
     import demoManifest from '$lib/demo-manifest.json'
 
@@ -45,16 +49,50 @@
     />
 {/snippet}
 
+{#snippet ttlNotes()}
+    <ul>
+        <li>
+            <Clock />
+            <span>
+                <code>ttl</code> sets the lifetime for every entry created by this
+                cache instance.
+            </span>
+        </li>
+        <li>
+            <Hourglass />
+            <span>
+                The list is sorted by <code>remainingMs</code>, so the next key to
+                expire stays at the top.
+            </span>
+        </li>
+        <li>
+            <TimerOff />
+            <span>
+                When an entry expires, <code>MemoryCache</code> stops returning it
+                and the active list removes it on the next tick.
+            </span>
+        </li>
+        <li>
+            <RotateCcw />
+            <span>
+                Changing <code>ttl</code> creates a fresh cache so countdowns,
+                expiration counts, and seed data stay aligned.
+            </span>
+        </li>
+    </ul>
+{/snippet}
+
 <ExampleV2
     figId="FIG-001"
-    tag="EXPIRATION"
-    title={{ prefix: 'ttl ', accent: 'expiration', end: '.' }}
-    description="Create short-lived entries and watch time-to-live expiration remove them from the cache."
+    tag="EXPIRATION-WINDOW"
+    title={{ prefix: 'watch ttl ', accent: 'countdown', end: '.' }}
+    description="Create short-lived entries in a `MemoryCache` and watch each key disappear when its time-to-live window closes."
     sheetLabel="SHEET 01 / 01"
     barCells={[{ k: 'pattern', v: 'time to live' }]}
     sourceUrl={`${SOURCE_URL}ttl-expiration/demos/Default.svelte`}
     codeSnippet={defaultCode}
     codeLabel="show code"
+    notes={ttlNotes}
 >
     <TtlExpiration />
 </ExampleV2>

From 234553e4daf8825b9a8143e5c2f27a8d81829e50 Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 10:06:32 -0400
Subject: [PATCH 10/22] docs: add spring capacity meter to lru example

---
 .../lru-eviction/demos/Default.svelte         | 25 ++++++++++++++-----
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/docs/src/lib/examples/lru-eviction/demos/Default.svelte b/docs/src/lib/examples/lru-eviction/demos/Default.svelte
index ac64145..fbd89f5 100644
--- a/docs/src/lib/examples/lru-eviction/demos/Default.svelte
+++ b/docs/src/lib/examples/lru-eviction/demos/Default.svelte
@@ -1,10 +1,17 @@
 <script lang="ts">
     import { MemoryCache } from '@humanspeak/memory-cache'
+    import { motion, type MotionTransition } from '@humanspeak/svelte-motion'
     import MousePointer from '@lucide/svelte/icons/mouse-pointer'
     import Plus from '@lucide/svelte/icons/plus'
     import RotateCcw from '@lucide/svelte/icons/rotate-ccw'
 
     const defaultMaxSize = 5
+    const capacitySpring: MotionTransition = {
+        type: 'spring',
+        stiffness: 180,
+        damping: 24,
+        mass: 0.7
+    }
 
     type EntryDisplay = {
         key: string
@@ -22,6 +29,7 @@
     let accessCounter = $state(0)
 
     let capacityRatio = $derived(entries.length / maxSize)
+    let capacityScale = $derived(Math.min(capacityRatio, 1))
     let lruKey = $derived(entries[0]?.key ?? 'none')
     let mruKey = $derived(entries.at(-1)?.key ?? 'none')
 
@@ -105,10 +113,14 @@
                 <div
                     class="capacity-meter"
                     aria-label="Capacity meter"
-                    style={`--capacity: ${(capacityRatio * 100).toFixed(1)}%`}
                     class:full={entries.length >= maxSize}
                 >
-                    <span></span>
+                    <motion.div
+                        class="capacity-meter-fill"
+                        initial={false}
+                        animate={{ scaleY: capacityScale }}
+                        transition={capacitySpring}
+                    />
                 </div>
             </div>
 
@@ -322,16 +334,17 @@
         padding: 6px;
     }
 
-    .capacity-meter span {
+    .capacity-meter :global(.capacity-meter-fill) {
         display: block;
         width: 100%;
-        height: var(--capacity);
+        height: 100%;
         min-height: 3px;
         background: var(--brut-accent);
-        transition: height 0.2s ease;
+        transform-origin: bottom;
+        will-change: transform;
     }
 
-    .capacity-meter.full span {
+    .capacity-meter.full :global(.capacity-meter-fill) {
         background: #dc2626;
     }
 

From 9023db94291f323bb27a1dd7e0e87ff563c78a56 Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 10:07:09 -0400
Subject: [PATCH 11/22] perf: lazy load example code samples

- Update docs-kit to the split demo manifest release
- Load example code panels from virtual demo modules
- Add local virtual module typing for lazy code samples
---
 docs/package.json                                      |  2 +-
 docs/src/routes/examples/basic-cache/+page.svelte      |  5 +----
 docs/src/routes/examples/cache-statistics/+page.svelte |  6 ++----
 docs/src/routes/examples/lru-eviction/+page.svelte     |  5 +----
 docs/src/routes/examples/ttl-expiration/+page.svelte   |  5 +----
 docs/src/virtual-demo.d.ts                             | 10 ++++++++++
 docs/vite.config.ts                                    |  2 +-
 pnpm-lock.yaml                                         | 10 +++++-----
 8 files changed, 22 insertions(+), 23 deletions(-)
 create mode 100644 docs/src/virtual-demo.d.ts

diff --git a/docs/package.json b/docs/package.json
index c87c4e7..ef9eb5a 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -18,7 +18,7 @@
         "preview": "vite preview"
     },
     "dependencies": {
-        "@humanspeak/docs-kit": "github:humanspeak/docs-kit#2026.6.5",
+        "@humanspeak/docs-kit": "github:humanspeak/docs-kit#2026.6.7",
         "@humanspeak/memory-cache": "workspace:*",
         "@humanspeak/svelte-markdown": "^1.5.4",
         "github-slugger": "^2.0.0",
diff --git a/docs/src/routes/examples/basic-cache/+page.svelte b/docs/src/routes/examples/basic-cache/+page.svelte
index f1c4bde..531ce2e 100644
--- a/docs/src/routes/examples/basic-cache/+page.svelte
+++ b/docs/src/routes/examples/basic-cache/+page.svelte
@@ -1,7 +1,6 @@
 <script lang="ts">
     import {
         CodeReferenceV2,
-        type DemoManifestEntry,
         ExampleV2,
         getBreadcrumbContext,
         getSeoContext
@@ -11,11 +10,9 @@
     import SearchX from '@lucide/svelte/icons/search-x'
     import Sparkles from '@lucide/svelte/icons/sparkles'
     import BasicCache from '$lib/examples/basic-cache/demos/Default.svelte'
-    import demoManifest from '$lib/demo-manifest.json'
 
     const SOURCE_URL =
         'https://github.com/humanspeak/memory-cache/blob/main/docs/src/lib/examples/'
-    const manifest = demoManifest as Record<string, DemoManifestEntry>
 
     const breadcrumbs = getBreadcrumbContext()
     const seo = getSeoContext()
@@ -42,7 +39,7 @@
             {
                 id: 'basic-cache-default',
                 label: 'Default.svelte',
-                ...manifest['basic-cache/demos/Default.svelte']
+                load: () => import('virtual:docs-kit/demo/basic-cache/demos/Default.svelte')
             }
         ]}
         columns={1}
diff --git a/docs/src/routes/examples/cache-statistics/+page.svelte b/docs/src/routes/examples/cache-statistics/+page.svelte
index 7db46ed..6be8863 100644
--- a/docs/src/routes/examples/cache-statistics/+page.svelte
+++ b/docs/src/routes/examples/cache-statistics/+page.svelte
@@ -1,7 +1,6 @@
 <script lang="ts">
     import {
         CodeReferenceV2,
-        type DemoManifestEntry,
         ExampleV2,
         getBreadcrumbContext,
         getSeoContext
@@ -11,11 +10,9 @@
     import ListRestart from '@lucide/svelte/icons/list-restart'
     import Zap from '@lucide/svelte/icons/zap'
     import CacheStatistics from '$lib/examples/cache-statistics/demos/Default.svelte'
-    import demoManifest from '$lib/demo-manifest.json'
 
     const SOURCE_URL =
         'https://github.com/humanspeak/memory-cache/blob/main/docs/src/lib/examples/'
-    const manifest = demoManifest as Record<string, DemoManifestEntry>
 
     const breadcrumbs = getBreadcrumbContext()
     const seo = getSeoContext()
@@ -42,7 +39,8 @@
             {
                 id: 'cache-statistics-default',
                 label: 'Default.svelte',
-                ...manifest['cache-statistics/demos/Default.svelte']
+                load: () =>
+                    import('virtual:docs-kit/demo/cache-statistics/demos/Default.svelte')
             }
         ]}
         columns={1}
diff --git a/docs/src/routes/examples/lru-eviction/+page.svelte b/docs/src/routes/examples/lru-eviction/+page.svelte
index 6a4f766..360ed65 100644
--- a/docs/src/routes/examples/lru-eviction/+page.svelte
+++ b/docs/src/routes/examples/lru-eviction/+page.svelte
@@ -1,7 +1,6 @@
 <script lang="ts">
     import {
         CodeReferenceV2,
-        type DemoManifestEntry,
         ExampleV2,
         getBreadcrumbContext,
         getSeoContext
@@ -11,11 +10,9 @@
     import Plus from '@lucide/svelte/icons/plus'
     import RotateCcw from '@lucide/svelte/icons/rotate-ccw'
     import LruEviction from '$lib/examples/lru-eviction/demos/Default.svelte'
-    import demoManifest from '$lib/demo-manifest.json'
 
     const SOURCE_URL =
         'https://github.com/humanspeak/memory-cache/blob/main/docs/src/lib/examples/'
-    const manifest = demoManifest as Record<string, DemoManifestEntry>
 
     const breadcrumbs = getBreadcrumbContext()
     const seo = getSeoContext()
@@ -42,7 +39,7 @@
             {
                 id: 'lru-eviction-default',
                 label: 'Default.svelte',
-                ...manifest['lru-eviction/demos/Default.svelte']
+                load: () => import('virtual:docs-kit/demo/lru-eviction/demos/Default.svelte')
             }
         ]}
         columns={1}
diff --git a/docs/src/routes/examples/ttl-expiration/+page.svelte b/docs/src/routes/examples/ttl-expiration/+page.svelte
index 0279693..c4bed62 100644
--- a/docs/src/routes/examples/ttl-expiration/+page.svelte
+++ b/docs/src/routes/examples/ttl-expiration/+page.svelte
@@ -1,7 +1,6 @@
 <script lang="ts">
     import {
         CodeReferenceV2,
-        type DemoManifestEntry,
         ExampleV2,
         getBreadcrumbContext,
         getSeoContext
@@ -11,11 +10,9 @@
     import RotateCcw from '@lucide/svelte/icons/rotate-ccw'
     import TimerOff from '@lucide/svelte/icons/timer-off'
     import TtlExpiration from '$lib/examples/ttl-expiration/demos/Default.svelte'
-    import demoManifest from '$lib/demo-manifest.json'
 
     const SOURCE_URL =
         'https://github.com/humanspeak/memory-cache/blob/main/docs/src/lib/examples/'
-    const manifest = demoManifest as Record<string, DemoManifestEntry>
 
     const breadcrumbs = getBreadcrumbContext()
     const seo = getSeoContext()
@@ -42,7 +39,7 @@
             {
                 id: 'ttl-expiration-default',
                 label: 'Default.svelte',
-                ...manifest['ttl-expiration/demos/Default.svelte']
+                load: () => import('virtual:docs-kit/demo/ttl-expiration/demos/Default.svelte')
             }
         ]}
         columns={1}
diff --git a/docs/src/virtual-demo.d.ts b/docs/src/virtual-demo.d.ts
new file mode 100644
index 0000000..563e450
--- /dev/null
+++ b/docs/src/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
+}
diff --git a/docs/vite.config.ts b/docs/vite.config.ts
index 35d90db..d6369f6 100644
--- a/docs/vite.config.ts
+++ b/docs/vite.config.ts
@@ -15,7 +15,7 @@ import { docsConfig } from './src/lib/docs-config'
 export default defineConfig({
     plugins: [
         sitemapManifestPlugin({ blogDir: false }),
-        demoManifestPlugin(),
+        demoManifestPlugin({ split: true }),
         docMirrorsPlugin({ siteUrl: docsConfig.url }),
         llmsFullPlugin({
             siteUrl: docsConfig.url,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d9e2089..6b63710 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -81,8 +81,8 @@ importers:
   docs:
     dependencies:
       '@humanspeak/docs-kit':
-        specifier: github:humanspeak/docs-kit#2026.6.5
-        version: https://codeload.github.com/humanspeak/docs-kit/tar.gz/e1198d98213319920f43eceaa83eef3a5b7854b1(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))
+        specifier: github:humanspeak/docs-kit#2026.6.7
+        version: https://codeload.github.com/humanspeak/docs-kit/tar.gz/ceab57acc4e85c51874d84fcb70c7c273d87c7f7(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))
       '@humanspeak/memory-cache':
         specifier: workspace:*
         version: link:..
@@ -672,8 +672,8 @@ packages:
     resolution: {integrity: sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q==}
     engines: {node: '>=18.18.0'}
 
-  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/e1198d98213319920f43eceaa83eef3a5b7854b1':
-    resolution: {gitHosted: true, integrity: sha512-6DRISAXr36xDU6zHqvAmCPZdY3tQJyjljfrj/dv8D6JAu3xrb2IdKbfZjGmRL+ACNpyBeEMyED8ZNJ1Q34RGrQ==, tarball: https://codeload.github.com/humanspeak/docs-kit/tar.gz/e1198d98213319920f43eceaa83eef3a5b7854b1}
+  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/ceab57acc4e85c51874d84fcb70c7c273d87c7f7':
+    resolution: {gitHosted: true, integrity: sha512-2ZY7YGwuIbN/0csiI1OEZaRYe9OhoXRSysfCF9AVAnauPNYy2dQwM6MkdGmHOrLSmRAnFocbmJPIsD7H7ovP6Q==, tarball: https://codeload.github.com/humanspeak/docs-kit/tar.gz/ceab57acc4e85c51874d84fcb70c7c273d87c7f7}
     version: 0.0.0
     peerDependencies:
       '@humanspeak/svelte-markdown': '>=1.0.0'
@@ -3325,7 +3325,7 @@ snapshots:
 
   '@humanfs/types@0.15.0': {}
 
-  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/e1198d98213319920f43eceaa83eef3a5b7854b1(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))':
+  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/ceab57acc4e85c51874d84fcb70c7c273d87c7f7(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))':
     dependencies:
       '@humanspeak/svelte-motion': 0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))
       '@humanspeak/svelte-satori-fix': 0.0.6(svelte@5.56.0(@typescript-eslint/types@8.60.0))

From 1ece9ec8d3c94eaf7c4be269e06c1b939b935dee Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 10:42:08 -0400
Subject: [PATCH 12/22] docs: update homepage hero

Bring the homepage masthead in line with the upstream brutalist hero
while keeping the existing feature and code sections in place.
---
 docs/src/routes/+page.svelte | 560 ++++++++++++++++++++---------------
 1 file changed, 324 insertions(+), 236 deletions(-)

diff --git a/docs/src/routes/+page.svelte b/docs/src/routes/+page.svelte
index 9b1310d..d4638e6 100644
--- a/docs/src/routes/+page.svelte
+++ b/docs/src/routes/+page.svelte
@@ -2,82 +2,37 @@
     import Header from '$lib/components/general/Header.svelte'
     import Footer from '$lib/components/general/Footer.svelte'
     import { getBreadcrumbContext } from '@humanspeak/docs-kit'
+    import { AnimatePresence, MotionButton, MotionSpan } from '@humanspeak/svelte-motion'
     import ArrowRight from '@lucide/svelte/icons/arrow-right'
     import AtSign from '@lucide/svelte/icons/at-sign'
-    import Book from '@lucide/svelte/icons/book'
     import Clock from '@lucide/svelte/icons/clock'
     import Feather from '@lucide/svelte/icons/feather'
     import FileCode from '@lucide/svelte/icons/file-code'
     import Layers from '@lucide/svelte/icons/layers'
-    import Play from '@lucide/svelte/icons/play'
-    import Rocket from '@lucide/svelte/icons/rocket'
     import Zap from '@lucide/svelte/icons/zap'
+    import packageJson from '../../../package.json'
     import type { Component } from 'svelte'
 
-    let headingContainer: HTMLDivElement | null = $state(null)
     const breadcrumbContext = getBreadcrumbContext()
 
     if (breadcrumbContext) {
         breadcrumbContext.breadcrumbs = []
     }
 
-    // Simple spring-like tap animation using the Web Animations API
-    function springTap(node: HTMLElement, options: { pressedScale?: number } = {}) {
-        const pressedScale = options.pressedScale ?? 0.96
-        let downAnim: Animation | null = null
-        let upAnim: Animation | null = null
-
-        const press = () => {
-            upAnim?.cancel()
-            downAnim?.cancel()
-            downAnim = node.animate(
-                [{ transform: 'scale(1)' }, { transform: `scale(${pressedScale})` }],
-                {
-                    duration: 120,
-                    easing: 'cubic-bezier(0.2, 0.8, 0.2, 1)',
-                    fill: 'forwards'
-                }
-            )
-        }
-
-        const release = () => {
-            downAnim?.cancel()
-            upAnim?.cancel()
-            upAnim = node.animate(
-                [
-                    { transform: `scale(${pressedScale})` },
-                    { transform: 'scale(1.03)' },
-                    { transform: 'scale(1)' }
-                ],
-                {
-                    duration: 220,
-                    easing: 'cubic-bezier(0.2, 0.8, 0.2, 1)',
-                    fill: 'forwards'
-                }
-            )
-        }
+    const PKG_NAME = packageJson.name
+    const PKG_VERSION = packageJson.version
+    const DEP_COUNT = 0
+    const installCmd = `npm i ${PKG_NAME}`
+    let copied = $state(false)
 
-        const onPointerDown = () => press()
-        const onPointerUp = () => release()
-        const onPointerLeave = () => release()
-        const onBlur = () => release()
-
-        node.addEventListener('pointerdown', onPointerDown)
-        node.addEventListener('pointerup', onPointerUp)
-        node.addEventListener('pointerleave', onPointerLeave)
-        node.addEventListener('blur', onBlur)
-
-        node.style.touchAction = 'manipulation'
-
-        return {
-            destroy() {
-                node.removeEventListener('pointerdown', onPointerDown)
-                node.removeEventListener('pointerup', onPointerUp)
-                node.removeEventListener('pointerleave', onPointerLeave)
-                node.removeEventListener('blur', onBlur)
-                downAnim?.cancel()
-                upAnim?.cancel()
-            }
+    const copyInstall = async () => {
+        if (typeof navigator === 'undefined') return
+        try {
+            await navigator.clipboard.writeText(installCmd)
+            copied = true
+            setTimeout(() => (copied = false), 1500)
+        } catch {
+            /* clipboard blocked - fail quiet */
         }
     }
 
@@ -120,144 +75,86 @@
         }
     ]
 
-    function splitHeadingWords(root: HTMLElement) {
-        const lines = root.querySelectorAll('h1 span')
-        const words: HTMLElement[] = []
-        lines.forEach((line) => {
-            const text = line.textContent ?? ''
-            line.textContent = ''
-            const tokens = text.split(/(\s+)/)
-            for (const t of tokens) {
-                if (t.trim().length === 0) {
-                    line.appendChild(document.createTextNode(t))
-                } else {
-                    const w = document.createElement('span')
-                    w.className = 'split-word'
-                    w.textContent = t
-                    line.appendChild(w)
-                    words.push(w)
-                }
-            }
-        })
-        return words
-    }
-
-    $effect(() => {
-        if (typeof document === 'undefined') return
-        if (!headingContainer) return
-        headingContainer.style.visibility = 'hidden'
-        document.fonts?.ready
-            .then(() => {
-                if (!headingContainer) return
-                const words = splitHeadingWords(headingContainer)
-                headingContainer.style.visibility = 'visible'
-                words.forEach((el, i) => {
-                    el.animate(
-                        [
-                            { opacity: 0, transform: 'translateY(10px)' },
-                            { opacity: 1, transform: 'translateY(0)' }
-                        ],
-                        {
-                            duration: 800,
-                            easing: 'ease-out',
-                            delay: i * 50,
-                            fill: 'forwards'
-                        }
-                    )
-                })
-            })
-            .catch(() => {
-                headingContainer!.style.visibility = 'visible'
-            })
-    })
 </script>
 
-<div class="flex min-h-svh flex-col">
+<div class="brut-wrap flex min-h-svh flex-col">
     <Header />
     <div class="relative flex flex-1 flex-col overflow-hidden">
-        <!-- Layer: subtle grid -->
-        <div class="bg-grid pointer-events-none absolute inset-0 -z-20"></div>
-        <!-- Layer: soft radial glow -->
-        <div class="bg-glow pointer-events-none absolute inset-0 -z-10"></div>
-        <!-- Layer: animated orbs -->
-        <div
-            class="orb-a-bg pointer-events-none absolute bottom-[-80px] left-[-80px] h-[320px] w-[320px] rounded-full opacity-50 blur-[30px]"
-            style="will-change: transform;"
-        ></div>
-        <div
-            class="orb-b-bg pointer-events-none absolute top-[20%] right-[-60px] h-[260px] w-[260px] rounded-full opacity-50 blur-[30px]"
-            style="will-change: transform;"
-        ></div>
-
-        <!-- Hero Section -->
-        <section class="relative flex flex-1">
-            <div
-                class="relative mx-auto flex w-full max-w-7xl items-center justify-center px-6 py-8 md:py-12"
-            >
-                <div class="mx-auto max-w-4xl text-center">
-                    <div bind:this={headingContainer} class="mx-auto max-w-4xl text-center">
-                        <h1
-                            class="text-5xl leading-tight font-semibold text-balance text-foreground md:text-7xl"
-                        >
-                            <span class="block">Memory</span>
-                            <span
-                                class="sheen-gradient block bg-gradient-to-r from-foreground via-brand-500 to-foreground bg-clip-text text-transparent"
+        <main class="brut">
+            <div class="brut-coord" aria-hidden="true">
+                {#each Array.from({ length: 12 }, (_, i) => i) as i (i)}
+                    <div>{String(i + 1).padStart(2, '0')}</div>
+                {/each}
+            </div>
+
+            <section class="brut-hero">
+                <div class="corner tr">FIG-001 · MASTHEAD</div>
+                <aside class="meta">
+                    <div><span class="k">pkg</span> · <span class="v">{PKG_NAME}</span></div>
+                    <div><span class="k">version</span> · <span class="v">{PKG_VERSION}</span></div>
+                    <div><span class="k">deps</span> · <span class="v">{DEP_COUNT}</span></div>
+                    <div><span class="k">licence</span> · <span class="v">MIT</span></div>
+                    <hr />
+                    <div><span class="k">ttl</span> · <span class="v accent">expiration</span></div>
+                    <div><span class="k">lru</span> · <span class="v">eviction</span></div>
+                    <div><span class="k">decorator</span> · <span class="v">@cached</span></div>
+                    <hr />
+                    <div class="k">// scroll for full spec</div>
+                </aside>
+                <div class="hero-body">
+                    <h1>
+                        <span class="mark" aria-hidden="true">
+                            <span>memory</span><span class="slash">/</span><span>cache</span><span
+                                class="end">.</span
                             >
-                                Cache
-                            </span>
-                        </h1>
-                        <p
-                            class="mt-6 text-base leading-7 text-pretty text-muted-foreground md:text-lg"
+                        </span>
+                        <span class="sr-only"
+                            >Memory Cache - a lightweight TypeScript in-memory caching library</span
                         >
-                            A high-performance, in-memory caching library for TypeScript. TTL expiration,
-                            LRU eviction, and a powerful @cached decorator—all in a zero-dependency package.
-                        </p>
-                        <div class="mt-8 flex flex-wrap items-center justify-center gap-3">
-                            <a
-                                href="/docs/getting-started"
-                                class="inline-flex items-center justify-center rounded-md bg-brand-600 px-4 py-2 text-sm font-medium text-white shadow transition-colors hover:bg-brand-700 focus:outline-none focus-visible:ring-2 focus-visible:ring-brand-600/30"
-                                use:springTap
-                            >
-                                Get Started
-                                <Rocket size={14} class="ml-2" />
-                            </a>
-                            <a
-                                href="/docs/api/memory-cache"
-                                class="inline-flex items-center justify-center rounded-md border border-border bg-card px-4 py-2 text-sm font-medium text-foreground transition-colors hover:border-brand-500/50 hover:text-brand-700 focus:outline-none focus-visible:ring-2 focus-visible:ring-brand-600/20"
-                                use:springTap
-                            >
-                                API Reference
-                                <Book size={14} class="ml-2" />
-                            </a>
-                            <a
-                                href="/examples"
-                                class="inline-flex items-center justify-center rounded-md border border-border bg-card px-4 py-2 text-sm font-medium text-foreground transition-colors hover:border-brand-500/50 hover:text-brand-700 focus:outline-none focus-visible:ring-2 focus-visible:ring-brand-600/20"
-                                use:springTap
-                            >
-                                Examples
-                                <Play size={14} class="ml-2" />
-                            </a>
-                        </div>
-                        <ul
-                            class="mt-10 flex flex-wrap justify-center gap-2 text-xs text-muted-foreground"
+                    </h1>
+                    <p class="sub">
+                        <b>Zero-dependency caching for TypeScript.</b> In-memory
+                        <code>MemoryCache</code> storage with TTL expiration, LRU eviction, wildcard
+                        pattern deletion, and a powerful <code>@cached</code> decorator for method-level
+                        memoization. Built for API responses, sessions, computed values, and fast local
+                        data reuse.
+                    </p>
+                    <div class="cta-row">
+                        <a class="pri" href="/docs/getting-started">get started ↗</a>
+                        <a href="/docs/api/memory-cache">api reference</a>
+                        <a href="/examples">examples</a>
+                        <MotionButton
+                            class="inst"
+                            type="button"
+                            onclick={copyInstall}
+                            aria-label="Copy install command"
+                            whileTap={{ scale: 0.97 }}
+                            whileHover={{ scale: 1.01 }}
+                            transition={{ type: 'spring', stiffness: 360, damping: 26 }}
                         >
-                            <li class="rounded-full border border-border-muted px-3 py-1">
-                                Zero Dependencies
-                            </li>
-                            <li class="rounded-full border border-border-muted px-3 py-1">
-                                TypeScript
-                            </li>
-                            <li class="rounded-full border border-border-muted px-3 py-1">
-                                TTL + LRU
-                            </li>
-                            <li class="rounded-full border border-border-muted px-3 py-1">
-                                Decorator Support
-                            </li>
-                        </ul>
+                            <span class="inst-prompt">$</span>
+                            <span class="inst-cmd">npm i <span class="pkg">{PKG_NAME}</span></span>
+                            <span class="inst-copy {copied ? 'is-copied' : ''}">
+                                <AnimatePresence initial={false}>
+                                    <MotionSpan
+                                        key={copied ? 'copied' : 'idle'}
+                                        class="inst-copy-label"
+                                        initial={{ opacity: 0, y: 6 }}
+                                        animate={{ opacity: 1, y: 0 }}
+                                        exit={{ opacity: 0, y: -6 }}
+                                        transition={{ duration: 0.18, ease: 'easeOut' }}
+                                    >
+                                        {copied ? 'copied' : 'copy'}
+                                    </MotionSpan>
+                                </AnimatePresence>
+                            </span>
+                        </MotionButton>
                     </div>
                 </div>
-            </div>
-        </section>
+                <div class="corner bl">FIG-001</div>
+                <div class="corner br">SHEET 01 / 03</div>
+            </section>
+        </main>
 
         <!-- Features Section -->
         <section class="relative px-6 py-10">
@@ -365,62 +262,253 @@ cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span clas
 </div>
 
 <style>
-    /* Decorative layers */
-    .bg-grid {
-        background-image: radial-gradient(rgba(255, 255, 255, 0.06) 1px, transparent 1px);
-        background-size: 24px 24px;
-        background-position: 50% 0;
-        mask-image: radial-gradient(ellipse at center, rgba(0, 0, 0, 1) 20%, rgba(0, 0, 0, 0) 70%);
+    .brut-coord {
+        display: grid;
+        grid-template-columns: repeat(12, 1fr);
+        border-bottom: 1px solid var(--brut-rule);
+        color: var(--brut-ink-3);
+        font-size: 10px;
+        letter-spacing: 0.14em;
     }
-    .bg-glow {
-        background:
-            radial-gradient(60% 50% at 50% 0%, rgba(84, 219, 188, 0.18), transparent 60%),
-            radial-gradient(40% 40% at 90% 20%, rgba(84, 219, 188, 0.12), transparent 60%),
-            radial-gradient(40% 40% at 10% 15%, rgba(84, 219, 188, 0.12), transparent 60%);
-        filter: blur(0.2px);
+
+    .brut-coord div {
+        border-right: 1px solid var(--brut-rule);
+        padding: 6px 8px;
     }
 
-    .orb-a-bg {
-        animation: orbA 28s ease-in-out infinite;
+    .brut-coord div:last-child {
+        border-right: 0;
     }
-    .orb-b-bg {
-        animation: orbB 24s ease-in-out infinite;
-        animation-delay: 3s;
+
+    .brut-hero {
+        position: relative;
+        display: grid;
+        grid-template-columns: 220px 1fr;
+        gap: 24px;
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 80px 24px 32px;
     }
 
-    @keyframes orbA {
-        0% {
-            transform: translate(0, 0);
-        }
-        25% {
-            transform: translate(8vw, -10vh);
-        }
-        50% {
-            transform: translate(-4vw, 6vh);
-        }
-        75% {
-            transform: translate(2vw, -4vh);
-        }
-        100% {
-            transform: translate(0, 0);
-        }
+    .brut-hero .meta {
+        display: flex;
+        margin: 0;
+        flex-direction: column;
+        gap: 8px;
+        color: var(--brut-ink-3);
+        font-size: 11px;
     }
 
-    @keyframes orbB {
-        0% {
-            transform: translate(0, 0);
-        }
-        25% {
-            transform: translate(-6vw, -8vh);
-        }
-        50% {
-            transform: translate(3vw, 4vh);
-        }
-        75% {
-            transform: translate(-2vw, -6vh);
+    .brut-hero .meta .k {
+        color: var(--brut-ink-3);
+    }
+
+    .brut-hero .meta .v {
+        color: var(--brut-ink);
+    }
+
+    .brut-hero .meta .v.accent {
+        color: var(--brut-accent);
+    }
+
+    .brut-hero .meta hr {
+        margin: 8px 0;
+        border: 0;
+        border-top: 1px dashed var(--brut-rule);
+    }
+
+    .brut-hero h1 {
+        margin: 0;
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-size: clamp(56px, 11vw, 152px);
+        font-weight: 500;
+        line-height: 0.88;
+        letter-spacing: -0.06em;
+        text-transform: lowercase;
+    }
+
+    .brut-hero h1 .slash {
+        color: var(--brut-accent);
+    }
+
+    .brut-hero h1 .end {
+        color: var(--brut-ink-3);
+    }
+
+    .brut-hero .sub {
+        max-width: 720px;
+        margin: 28px 0 0;
+        color: var(--brut-ink-2);
+        font-family: 'Inter Variable', 'Inter', system-ui, sans-serif;
+        font-size: 17px;
+        line-height: 1.5;
+        letter-spacing: -0.01em;
+    }
+
+    .brut-hero .sub b {
+        color: var(--brut-ink);
+        font-weight: 600;
+    }
+
+    .brut-hero .sub code {
+        border: 1px solid var(--brut-rule);
+        background: var(--brut-bg-2);
+        color: var(--brut-ink);
+        padding: 0 5px;
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-size: 14.5px;
+    }
+
+    .brut-hero .cta-row {
+        display: flex;
+        width: fit-content;
+        max-width: 100%;
+        align-items: stretch;
+        flex-wrap: wrap;
+        gap: 0;
+        margin-top: 28px;
+    }
+
+    .brut-hero .cta-row > * {
+        position: relative;
+        z-index: 1;
+        display: inline-flex;
+        align-items: center;
+        gap: 8px;
+        border: 1px solid var(--brut-rule);
+        background: var(--brut-bg);
+        color: var(--brut-ink);
+        padding: 10px 14px;
+        font-family: inherit;
+        font-size: 13px;
+        text-decoration: none;
+        cursor: pointer;
+        transition:
+            background 0.15s,
+            border-color 0.15s;
+    }
+
+    .brut-hero .cta-row > * + * {
+        margin-left: -1px;
+    }
+
+    .brut-hero .cta-row > *:hover {
+        z-index: 2;
+    }
+
+    .brut-hero .cta-row .pri {
+        border-color: var(--brut-accent);
+        background: var(--brut-accent);
+        color: var(--brut-accent-ink);
+        font-weight: 600;
+    }
+
+    .brut-hero .cta-row .pri:hover {
+        border-color: var(--brut-accent-hover);
+        background: var(--brut-accent-hover);
+    }
+
+    .brut-hero .cta-row a:not(.pri):hover,
+    .brut-hero .cta-row :global(.inst:hover) {
+        border-color: var(--brut-rule-2);
+        background: var(--brut-bg-2);
+    }
+
+    .brut-hero .cta-row :global(.inst) {
+        position: relative;
+        z-index: 1;
+        display: inline-flex;
+        align-items: center;
+        gap: 10px;
+        margin-left: -1px;
+        border: 1px solid var(--brut-rule);
+        background: var(--brut-bg-2);
+        color: var(--brut-ink-2);
+        padding: 10px 18px;
+        font-family: inherit;
+        font-size: 13px;
+        cursor: pointer;
+        transition:
+            background 0.15s,
+            border-color 0.15s;
+    }
+
+    .brut-hero .cta-row :global(.inst:hover) {
+        z-index: 2;
+    }
+
+    .brut-hero .cta-row :global(.inst .inst-prompt) {
+        color: var(--brut-ink-3);
+    }
+
+    .brut-hero .cta-row :global(.inst .inst-cmd) {
+        color: var(--brut-ink-2);
+    }
+
+    .brut-hero .cta-row :global(.inst .inst-cmd .pkg) {
+        color: var(--brut-ink);
+    }
+
+    .brut-hero .cta-row :global(.inst .inst-copy) {
+        display: inline-grid;
+        width: 84px;
+        height: 20px;
+        align-items: center;
+        justify-items: center;
+        margin-left: 4px;
+        overflow: hidden;
+        border: 1px solid var(--brut-rule);
+        color: var(--brut-accent);
+        padding: 2px 8px;
+        font-size: 10.5px;
+        letter-spacing: 0.14em;
+        text-transform: uppercase;
+        transition:
+            border-color 0.2s,
+            background 0.2s;
+    }
+
+    .brut-hero .cta-row :global(.inst .inst-copy.is-copied) {
+        border-color: var(--brut-accent);
+        background: var(--brut-accent-soft);
+    }
+
+    .brut-hero .cta-row :global(.inst .inst-copy-label) {
+        grid-area: 1 / 1;
+        display: inline-block;
+        white-space: nowrap;
+        will-change: transform, opacity;
+    }
+
+    .brut-hero .corner {
+        position: absolute;
+        color: var(--brut-ink-3);
+        font-size: 10px;
+        letter-spacing: 0.14em;
+    }
+
+    .brut-hero .corner.tr {
+        top: 12px;
+        right: 24px;
+    }
+
+    .brut-hero .corner.bl {
+        bottom: 12px;
+        left: 24px;
+    }
+
+    .brut-hero .corner.br {
+        right: 24px;
+        bottom: 12px;
+    }
+
+    @media (max-width: 720px) {
+        .brut-coord {
+            display: none;
         }
-        100% {
-            transform: translate(0, 0);
+
+        .brut-hero {
+            grid-template-columns: 1fr;
+            padding: 56px 16px 32px;
         }
     }
 </style>

From 0a1eb75e87cd52cb361334ff04d85765babff41c Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 10:42:41 -0400
Subject: [PATCH 13/22] fix: improve docs first paint theme

Set the stored theme class before generated CSS reaches the page and
mirror upstream chunking for motion and mode-watcher client code.
---
 docs/src/app.html              | 22 +++++++++++++++++++---
 docs/src/routes/+layout.svelte |  3 +--
 docs/vite.config.ts            | 10 ++++++++++
 3 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/docs/src/app.html b/docs/src/app.html
index 637d0ff..851e8fd 100644
--- a/docs/src/app.html
+++ b/docs/src/app.html
@@ -2,18 +2,34 @@
 <html lang="en">
     <head>
         <meta charset="utf-8" />
-        <link rel="icon" href="%sveltekit.assets%/logo.svg" />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
         <meta name="theme-color" content="#54dbbc" />
+        <script nonce="%sveltekit.nonce%">
+            ;(() => {
+                try {
+                    const root = document.documentElement
+                    const mode = localStorage.getItem('mode-watcher-mode') ?? 'system'
+                    const light =
+                        mode === 'light' ||
+                        (mode === 'system' &&
+                            window.matchMedia('(prefers-color-scheme: light)').matches)
+
+                    root.classList.toggle('dark', !light)
+                    root.style.colorScheme = light ? 'light' : 'dark'
+                } catch {
+                    /* ModeWatcher will resolve the theme after hydration. */
+                }
+            })()
+        </script>
         <link rel="preconnect" href="https://analytics.ahrefs.com" />
+        %sveltekit.head%
         <script
             src="https://analytics.ahrefs.com/analytics.js"
             data-key="Vfe1gM5v1Ss/cND8zjTWEg"
             async
         ></script>
-        %sveltekit.head%
     </head>
     <body data-sveltekit-preload-data="hover">
-        <div style="display: contents" class="w-full">%sveltekit.body%</div>
+        <div style="display: contents">%sveltekit.body%</div>
     </body>
 </html>
diff --git a/docs/src/routes/+layout.svelte b/docs/src/routes/+layout.svelte
index 6fc9600..6d2e45d 100644
--- a/docs/src/routes/+layout.svelte
+++ b/docs/src/routes/+layout.svelte
@@ -57,13 +57,12 @@
         '/script>'
 </script>
 
+<ModeWatcher />
 <svelte:head>
     <!-- JSON-LD structured data: SoftwareApplication -->
     <!-- trunk-ignore(eslint/svelte/no-at-html-tags) -->
     {@html softwareAppJsonLd}
 </svelte:head>
-
-<ModeWatcher />
 <SeoContextProvider {seo}>
     <SeoHead {seo} config={docsConfig} favicon="/logo.svg" />
     <BreadcrumbContextProvider>
diff --git a/docs/vite.config.ts b/docs/vite.config.ts
index d6369f6..6fa9bb6 100644
--- a/docs/vite.config.ts
+++ b/docs/vite.config.ts
@@ -42,6 +42,16 @@ export default defineConfig({
             'satori-html'
         ]
     },
+    build: {
+        rollupOptions: {
+            output: {
+                manualChunks(id) {
+                    if (id.includes('@humanspeak/svelte-motion')) return 'svelte-motion'
+                    if (id.includes('mode-watcher')) return 'mode-watcher'
+                }
+            }
+        }
+    },
     server: {
         port: 8288
     }

From 36a09f0408f22276a9c018561db9f1693637f61f Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 10:51:49 -0400
Subject: [PATCH 14/22] docs: add homepage package stats row

Fetch live npm package stats through docs-kit and surface the
version, tarball size, runtime deps, and API facts in the homepage
masthead area.
---
 docs/src/routes/+page.server.ts |  10 +++
 docs/src/routes/+page.svelte    | 145 ++++++++++++++++++++++++++++++--
 docs/src/routes/+page.ts        |   5 +-
 3 files changed, 151 insertions(+), 9 deletions(-)
 create mode 100644 docs/src/routes/+page.server.ts

diff --git a/docs/src/routes/+page.server.ts b/docs/src/routes/+page.server.ts
new file mode 100644
index 0000000..f149dc0
--- /dev/null
+++ b/docs/src/routes/+page.server.ts
@@ -0,0 +1,10 @@
+import { dev } from '$app/environment'
+import { createPackageStatsLoad } from '@humanspeak/docs-kit/server'
+import rootPkg from '../../../package.json'
+
+export const prerender = false
+
+export const load = createPackageStatsLoad({
+    pkg: rootPkg,
+    dev
+})
diff --git a/docs/src/routes/+page.svelte b/docs/src/routes/+page.svelte
index d4638e6..3947733 100644
--- a/docs/src/routes/+page.svelte
+++ b/docs/src/routes/+page.svelte
@@ -10,30 +10,60 @@
     import FileCode from '@lucide/svelte/icons/file-code'
     import Layers from '@lucide/svelte/icons/layers'
     import Zap from '@lucide/svelte/icons/zap'
-    import packageJson from '../../../package.json'
     import type { Component } from 'svelte'
+    import type { PageData } from './$types'
 
+    const { data }: { data: PageData } = $props()
+    const packageStats = $derived(data.packageStats)
     const breadcrumbContext = getBreadcrumbContext()
 
     if (breadcrumbContext) {
         breadcrumbContext.breadcrumbs = []
     }
 
-    const PKG_NAME = packageJson.name
-    const PKG_VERSION = packageJson.version
+    const PKG_NAME = $derived(packageStats.name)
+    const PKG_VERSION = $derived(packageStats.version)
+    const TARBALL_KB = $derived(
+        packageStats.tarballBytes !== null
+            ? Math.round(packageStats.tarballBytes / 102.4) / 10
+            : null
+    )
     const DEP_COUNT = 0
-    const installCmd = `npm i ${PKG_NAME}`
+    const installCmd = $derived(`npm i ${PKG_NAME}`)
     let copied = $state(false)
 
+    interface StatItem {
+        k: string
+        v: string
+        sup?: string
+        n: string
+        ac?: boolean
+    }
+
+    const stats: StatItem[] = $derived([
+        { k: 'exports', v: '3', n: 'MemoryCache · cached · types', ac: true },
+        { k: 'policies', v: '2', n: 'TTL · LRU eviction' },
+        { k: 'hooks', v: '6', n: 'hit · miss · set · evict · expire · delete', ac: true },
+        {
+            k: 'tarball',
+            v: TARBALL_KB !== null ? String(TARBALL_KB) : '—',
+            sup: TARBALL_KB !== null ? 'kB' : undefined,
+            n: 'packed (npm gz)'
+        },
+        { k: 'runtime deps', v: String(DEP_COUNT), n: 'zero-dependency runtime' },
+        { k: 'licence', v: 'MIT', n: 'on GitHub' }
+    ])
+
     const copyInstall = async () => {
         if (typeof navigator === 'undefined') return
         try {
-            await navigator.clipboard.writeText(installCmd)
-            copied = true
-            setTimeout(() => (copied = false), 1500)
+            await navigator.clipboard?.writeText(installCmd)
         } catch {
             /* clipboard blocked - fail quiet */
         }
+
+        copied = true
+        setTimeout(() => (copied = false), 1500)
     }
 
     const features: { title: string; description: string; icon: Component }[] = [
@@ -92,6 +122,10 @@
                 <aside class="meta">
                     <div><span class="k">pkg</span> · <span class="v">{PKG_NAME}</span></div>
                     <div><span class="k">version</span> · <span class="v">{PKG_VERSION}</span></div>
+                    <div>
+                        <span class="k">tarball</span> ·
+                        <span class="v">{TARBALL_KB !== null ? `${TARBALL_KB} kB gz` : '—'}</span>
+                    </div>
                     <div><span class="k">deps</span> · <span class="v">{DEP_COUNT}</span></div>
                     <div><span class="k">licence</span> · <span class="v">MIT</span></div>
                     <hr />
@@ -144,7 +178,7 @@
                                         exit={{ opacity: 0, y: -6 }}
                                         transition={{ duration: 0.18, ease: 'easeOut' }}
                                     >
-                                        {copied ? 'copied' : 'copy'}
+                                        {copied ? '✓ copied' : 'copy'}
                                     </MotionSpan>
                                 </AnimatePresence>
                             </span>
@@ -154,6 +188,20 @@
                 <div class="corner bl">FIG-001</div>
                 <div class="corner br">SHEET 01 / 03</div>
             </section>
+
+            <section class="brut-stats">
+                {#each stats as s, i (s.k)}
+                    <div class="s {s.ac ? 'ac' : ''}" data-idx="/0{i + 1}">
+                        <div class="k">{s.k}</div>
+                        <div class="v">
+                            <span class="v-num">{s.v}</span>{#if s.sup}<span class="v-unit"
+                                    >{s.sup}</span
+                                >{/if}
+                        </div>
+                        <div class="note">{s.n}</div>
+                    </div>
+                {/each}
+            </section>
         </main>
 
         <!-- Features Section -->
@@ -501,6 +549,74 @@ cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span clas
         bottom: 12px;
     }
 
+    .brut-stats {
+        display: grid;
+        grid-template-columns: repeat(6, 1fr);
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .brut-stats .s {
+        position: relative;
+        display: flex;
+        min-height: 160px;
+        flex-direction: column;
+        justify-content: space-between;
+        border-right: 1px solid var(--brut-rule);
+        padding: 28px 24px;
+    }
+
+    .brut-stats .s:last-child {
+        border-right: 0;
+    }
+
+    .brut-stats .s .k {
+        color: var(--brut-ink-3);
+        font-size: 10.5px;
+        letter-spacing: 0.14em;
+    }
+
+    .brut-stats .s .v {
+        display: inline-flex;
+        align-items: baseline;
+        gap: 4px;
+        color: var(--brut-ink);
+        font-size: 64px;
+        font-weight: 500;
+        line-height: 1;
+        letter-spacing: -0.04em;
+        white-space: nowrap;
+    }
+
+    .brut-stats .s .v-num {
+        line-height: 1;
+    }
+
+    .brut-stats .s .v-unit {
+        color: inherit;
+        font-size: 22px;
+        font-weight: 500;
+        line-height: 1;
+        letter-spacing: 0;
+    }
+
+    .brut-stats .s .note {
+        color: var(--brut-ink-2);
+        font-size: 11px;
+    }
+
+    .brut-stats .s.ac .v {
+        color: var(--brut-accent);
+    }
+
+    .brut-stats .s::after {
+        position: absolute;
+        top: 12px;
+        right: 14px;
+        color: var(--brut-ink-3);
+        font-size: 10px;
+        content: attr(data-idx);
+    }
+
     @media (max-width: 720px) {
         .brut-coord {
             display: none;
@@ -510,5 +626,18 @@ cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span clas
             grid-template-columns: 1fr;
             padding: 56px 16px 32px;
         }
+
+        .brut-stats {
+            grid-template-columns: repeat(2, 1fr);
+        }
+
+        .brut-stats .s {
+            min-height: 130px;
+            padding: 20px 16px;
+        }
+
+        .brut-stats .s .v {
+            font-size: 44px;
+        }
     }
 </style>
diff --git a/docs/src/routes/+page.ts b/docs/src/routes/+page.ts
index 0c80533..500c3f0 100644
--- a/docs/src/routes/+page.ts
+++ b/docs/src/routes/+page.ts
@@ -1,4 +1,7 @@
-export const load = () => ({
+import type { PageLoad } from './$types'
+
+export const load: PageLoad = ({ data }) => ({
+    ...data,
     title: 'Memory Cache - Lightweight TypeScript In-Memory Caching Library',
     description:
         'A lightweight, zero-dependency TypeScript in-memory caching library with TTL expiration, LRU eviction, and decorator support.'

From 274d9fbaf2e2a2fd1029cfbdfa628b34612b2a7c Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 11:13:29 -0400
Subject: [PATCH 15/22] perf: use generated demo code loaders

---
 .gitignore                                           |  1 +
 docs/.gitignore                                      |  3 ++-
 docs/package.json                                    |  2 +-
 docs/src/routes/examples/basic-cache/+page.svelte    |  7 ++-----
 .../routes/examples/cache-statistics/+page.svelte    | 12 ++++++------
 docs/src/routes/examples/lru-eviction/+page.svelte   | 11 ++++++-----
 docs/src/routes/examples/ttl-expiration/+page.svelte | 11 ++++++-----
 docs/src/virtual-demo.d.ts                           | 10 ----------
 pnpm-lock.yaml                                       | 10 +++++-----
 9 files changed, 29 insertions(+), 38 deletions(-)
 delete mode 100644 docs/src/virtual-demo.d.ts

diff --git a/.gitignore b/.gitignore
index a214fba..90866fa 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,4 +31,5 @@ docs/static/llms.txt
 mprocs.log
 docs/src/lib/github-stats.json
 docs/src/lib/demo-manifest.json
+docs/src/lib/demo-loaders.ts
 docs/src/lib/sitemap-manifest.json
diff --git a/docs/.gitignore b/docs/.gitignore
index 2e23468..aa499fa 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1 +1,2 @@
-.wrangler/
\ No newline at end of file
+.wrangler/
+src/lib/demo-loaders.ts
diff --git a/docs/package.json b/docs/package.json
index ef9eb5a..15da84a 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -18,7 +18,7 @@
         "preview": "vite preview"
     },
     "dependencies": {
-        "@humanspeak/docs-kit": "github:humanspeak/docs-kit#2026.6.7",
+        "@humanspeak/docs-kit": "github:humanspeak/docs-kit#2026.6.8",
         "@humanspeak/memory-cache": "workspace:*",
         "@humanspeak/svelte-markdown": "^1.5.4",
         "github-slugger": "^2.0.0",
diff --git a/docs/src/routes/examples/basic-cache/+page.svelte b/docs/src/routes/examples/basic-cache/+page.svelte
index 531ce2e..274411b 100644
--- a/docs/src/routes/examples/basic-cache/+page.svelte
+++ b/docs/src/routes/examples/basic-cache/+page.svelte
@@ -9,6 +9,7 @@
     import RotateCcw from '@lucide/svelte/icons/rotate-ccw'
     import SearchX from '@lucide/svelte/icons/search-x'
     import Sparkles from '@lucide/svelte/icons/sparkles'
+    import { demoCodeSample } from '$lib/demo-loaders'
     import BasicCache from '$lib/examples/basic-cache/demos/Default.svelte'
 
     const SOURCE_URL =
@@ -36,11 +37,7 @@
 {#snippet defaultCode()}
     <CodeReferenceV2
         samples={[
-            {
-                id: 'basic-cache-default',
-                label: 'Default.svelte',
-                load: () => import('virtual:docs-kit/demo/basic-cache/demos/Default.svelte')
-            }
+            demoCodeSample('basic-cache/demos/Default.svelte', 'basic-cache-default', 'Default.svelte')
         ]}
         columns={1}
     />
diff --git a/docs/src/routes/examples/cache-statistics/+page.svelte b/docs/src/routes/examples/cache-statistics/+page.svelte
index 6be8863..87dd44c 100644
--- a/docs/src/routes/examples/cache-statistics/+page.svelte
+++ b/docs/src/routes/examples/cache-statistics/+page.svelte
@@ -9,6 +9,7 @@
     import Gauge from '@lucide/svelte/icons/gauge'
     import ListRestart from '@lucide/svelte/icons/list-restart'
     import Zap from '@lucide/svelte/icons/zap'
+    import { demoCodeSample } from '$lib/demo-loaders'
     import CacheStatistics from '$lib/examples/cache-statistics/demos/Default.svelte'
 
     const SOURCE_URL =
@@ -36,12 +37,11 @@
 {#snippet defaultCode()}
     <CodeReferenceV2
         samples={[
-            {
-                id: 'cache-statistics-default',
-                label: 'Default.svelte',
-                load: () =>
-                    import('virtual:docs-kit/demo/cache-statistics/demos/Default.svelte')
-            }
+            demoCodeSample(
+                'cache-statistics/demos/Default.svelte',
+                'cache-statistics-default',
+                'Default.svelte'
+            )
         ]}
         columns={1}
     />
diff --git a/docs/src/routes/examples/lru-eviction/+page.svelte b/docs/src/routes/examples/lru-eviction/+page.svelte
index 360ed65..f6a2035 100644
--- a/docs/src/routes/examples/lru-eviction/+page.svelte
+++ b/docs/src/routes/examples/lru-eviction/+page.svelte
@@ -9,6 +9,7 @@
     import MousePointer from '@lucide/svelte/icons/mouse-pointer'
     import Plus from '@lucide/svelte/icons/plus'
     import RotateCcw from '@lucide/svelte/icons/rotate-ccw'
+    import { demoCodeSample } from '$lib/demo-loaders'
     import LruEviction from '$lib/examples/lru-eviction/demos/Default.svelte'
 
     const SOURCE_URL =
@@ -36,11 +37,11 @@
 {#snippet defaultCode()}
     <CodeReferenceV2
         samples={[
-            {
-                id: 'lru-eviction-default',
-                label: 'Default.svelte',
-                load: () => import('virtual:docs-kit/demo/lru-eviction/demos/Default.svelte')
-            }
+            demoCodeSample(
+                'lru-eviction/demos/Default.svelte',
+                'lru-eviction-default',
+                'Default.svelte'
+            )
         ]}
         columns={1}
     />
diff --git a/docs/src/routes/examples/ttl-expiration/+page.svelte b/docs/src/routes/examples/ttl-expiration/+page.svelte
index c4bed62..2b7060c 100644
--- a/docs/src/routes/examples/ttl-expiration/+page.svelte
+++ b/docs/src/routes/examples/ttl-expiration/+page.svelte
@@ -9,6 +9,7 @@
     import Hourglass from '@lucide/svelte/icons/hourglass'
     import RotateCcw from '@lucide/svelte/icons/rotate-ccw'
     import TimerOff from '@lucide/svelte/icons/timer-off'
+    import { demoCodeSample } from '$lib/demo-loaders'
     import TtlExpiration from '$lib/examples/ttl-expiration/demos/Default.svelte'
 
     const SOURCE_URL =
@@ -36,11 +37,11 @@
 {#snippet defaultCode()}
     <CodeReferenceV2
         samples={[
-            {
-                id: 'ttl-expiration-default',
-                label: 'Default.svelte',
-                load: () => import('virtual:docs-kit/demo/ttl-expiration/demos/Default.svelte')
-            }
+            demoCodeSample(
+                'ttl-expiration/demos/Default.svelte',
+                'ttl-expiration-default',
+                'Default.svelte'
+            )
         ]}
         columns={1}
     />
diff --git a/docs/src/virtual-demo.d.ts b/docs/src/virtual-demo.d.ts
deleted file mode 100644
index 563e450..0000000
--- a/docs/src/virtual-demo.d.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-declare module 'virtual:docs-kit/demo/*' {
-    interface DemoManifestEntry {
-        code: string
-        lang: string
-        html?: { light: string; dark: string }
-    }
-
-    const entry: DemoManifestEntry
-    export default entry
-}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6b63710..b97ecc0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -81,8 +81,8 @@ importers:
   docs:
     dependencies:
       '@humanspeak/docs-kit':
-        specifier: github:humanspeak/docs-kit#2026.6.7
-        version: https://codeload.github.com/humanspeak/docs-kit/tar.gz/ceab57acc4e85c51874d84fcb70c7c273d87c7f7(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))
+        specifier: github:humanspeak/docs-kit#2026.6.8
+        version: https://codeload.github.com/humanspeak/docs-kit/tar.gz/a95d0e126504c0caa3007ebbd4928d5a1bea2175(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))
       '@humanspeak/memory-cache':
         specifier: workspace:*
         version: link:..
@@ -672,8 +672,8 @@ packages:
     resolution: {integrity: sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q==}
     engines: {node: '>=18.18.0'}
 
-  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/ceab57acc4e85c51874d84fcb70c7c273d87c7f7':
-    resolution: {gitHosted: true, integrity: sha512-2ZY7YGwuIbN/0csiI1OEZaRYe9OhoXRSysfCF9AVAnauPNYy2dQwM6MkdGmHOrLSmRAnFocbmJPIsD7H7ovP6Q==, tarball: https://codeload.github.com/humanspeak/docs-kit/tar.gz/ceab57acc4e85c51874d84fcb70c7c273d87c7f7}
+  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/a95d0e126504c0caa3007ebbd4928d5a1bea2175':
+    resolution: {gitHosted: true, tarball: https://codeload.github.com/humanspeak/docs-kit/tar.gz/a95d0e126504c0caa3007ebbd4928d5a1bea2175}
     version: 0.0.0
     peerDependencies:
       '@humanspeak/svelte-markdown': '>=1.0.0'
@@ -3325,7 +3325,7 @@ snapshots:
 
   '@humanfs/types@0.15.0': {}
 
-  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/ceab57acc4e85c51874d84fcb70c7c273d87c7f7(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))':
+  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/a95d0e126504c0caa3007ebbd4928d5a1bea2175(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))':
     dependencies:
       '@humanspeak/svelte-motion': 0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))
       '@humanspeak/svelte-satori-fix': 0.0.6(svelte@5.56.0(@typescript-eslint/types@8.60.0))

From 8107af2ba2d1b3c4306e6c7e68b8d04ba790aa42 Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 12:09:55 -0400
Subject: [PATCH 16/22] build(docs): update docs-kit demo type generation

---
 .gitignore        |  1 +
 docs/.gitignore   |  1 +
 docs/package.json |  2 +-
 pnpm-lock.yaml    | 10 +++++-----
 4 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/.gitignore b/.gitignore
index 90866fa..e85a538 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,4 +32,5 @@ mprocs.log
 docs/src/lib/github-stats.json
 docs/src/lib/demo-manifest.json
 docs/src/lib/demo-loaders.ts
+docs/src/lib/demo-virtual.d.ts
 docs/src/lib/sitemap-manifest.json
diff --git a/docs/.gitignore b/docs/.gitignore
index aa499fa..fe4718c 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,2 +1,3 @@
 .wrangler/
 src/lib/demo-loaders.ts
+src/lib/demo-virtual.d.ts
diff --git a/docs/package.json b/docs/package.json
index 15da84a..f3f7b55 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -18,7 +18,7 @@
         "preview": "vite preview"
     },
     "dependencies": {
-        "@humanspeak/docs-kit": "github:humanspeak/docs-kit#2026.6.8",
+        "@humanspeak/docs-kit": "github:humanspeak/docs-kit#2026.6.9",
         "@humanspeak/memory-cache": "workspace:*",
         "@humanspeak/svelte-markdown": "^1.5.4",
         "github-slugger": "^2.0.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index b97ecc0..03f5ca4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -81,8 +81,8 @@ importers:
   docs:
     dependencies:
       '@humanspeak/docs-kit':
-        specifier: github:humanspeak/docs-kit#2026.6.8
-        version: https://codeload.github.com/humanspeak/docs-kit/tar.gz/a95d0e126504c0caa3007ebbd4928d5a1bea2175(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))
+        specifier: github:humanspeak/docs-kit#2026.6.9
+        version: https://codeload.github.com/humanspeak/docs-kit/tar.gz/480c160c9839e47f0856b707dff70147167ea845(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))
       '@humanspeak/memory-cache':
         specifier: workspace:*
         version: link:..
@@ -672,8 +672,8 @@ packages:
     resolution: {integrity: sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q==}
     engines: {node: '>=18.18.0'}
 
-  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/a95d0e126504c0caa3007ebbd4928d5a1bea2175':
-    resolution: {gitHosted: true, tarball: https://codeload.github.com/humanspeak/docs-kit/tar.gz/a95d0e126504c0caa3007ebbd4928d5a1bea2175}
+  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/480c160c9839e47f0856b707dff70147167ea845':
+    resolution: {gitHosted: true, tarball: https://codeload.github.com/humanspeak/docs-kit/tar.gz/480c160c9839e47f0856b707dff70147167ea845}
     version: 0.0.0
     peerDependencies:
       '@humanspeak/svelte-markdown': '>=1.0.0'
@@ -3325,7 +3325,7 @@ snapshots:
 
   '@humanfs/types@0.15.0': {}
 
-  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/a95d0e126504c0caa3007ebbd4928d5a1bea2175(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))':
+  '@humanspeak/docs-kit@https://codeload.github.com/humanspeak/docs-kit/tar.gz/480c160c9839e47f0856b707dff70147167ea845(@humanspeak/svelte-markdown@1.5.4(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@humanspeak/svelte-motion@0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@internationalized/date@3.12.0)(@lucide/svelte@1.17.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(@sveltejs/kit@2.61.1(@sveltejs/vite-plugin-svelte@7.1.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(svelte@5.56.0(@typescript-eslint/types@8.60.0))(typescript@6.0.3)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0)(tsx@4.22.4)))(mode-watcher@1.1.0(svelte@5.56.0(@typescript-eslint/types@8.60.0)))(shiki@4.1.0)(svelte@5.56.0(@typescript-eslint/types@8.60.0))':
     dependencies:
       '@humanspeak/svelte-motion': 0.6.2(svelte@5.56.0(@typescript-eslint/types@8.60.0))
       '@humanspeak/svelte-satori-fix': 0.0.6(svelte@5.56.0(@typescript-eslint/types@8.60.0))

From b37166306670189eca2e5586963793a86c73ae23 Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 12:10:47 -0400
Subject: [PATCH 17/22] fix(docs): allow nonce scripts in csp

---
 docs/svelte.config.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/svelte.config.js b/docs/svelte.config.js
index 7abdcfa..4980254 100644
--- a/docs/svelte.config.js
+++ b/docs/svelte.config.js
@@ -44,7 +44,7 @@ const config = {
         csp: {
             directives: {
                 'default-src': ['self'],
-                'script-src': ['self', 'https://analytics.ahrefs.com'],
+                'script-src': ['self', 'nonce-%sveltekit.nonce%', 'https://analytics.ahrefs.com'],
                 'style-src': ['self', 'unsafe-inline'],
                 'img-src': ['self', 'data:'],
                 'font-src': ['self'],

From a404d5f2db7f5a5db73e44213fc1e8a260216632 Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 12:11:40 -0400
Subject: [PATCH 18/22] feat(docs): add homepage cache telemetry demo

---
 docs/src/routes/+page.svelte | 652 ++++++++++++++++++++++++++++++++++-
 1 file changed, 634 insertions(+), 18 deletions(-)

diff --git a/docs/src/routes/+page.svelte b/docs/src/routes/+page.svelte
index 3947733..48e7269 100644
--- a/docs/src/routes/+page.svelte
+++ b/docs/src/routes/+page.svelte
@@ -2,7 +2,13 @@
     import Header from '$lib/components/general/Header.svelte'
     import Footer from '$lib/components/general/Footer.svelte'
     import { getBreadcrumbContext } from '@humanspeak/docs-kit'
-    import { AnimatePresence, MotionButton, MotionSpan } from '@humanspeak/svelte-motion'
+    import { MemoryCache } from '@humanspeak/memory-cache'
+    import {
+        AnimatePresence,
+        MotionButton,
+        MotionSpan,
+        type MotionTransition
+    } from '@humanspeak/svelte-motion'
     import ArrowRight from '@lucide/svelte/icons/arrow-right'
     import AtSign from '@lucide/svelte/icons/at-sign'
     import Clock from '@lucide/svelte/icons/clock'
@@ -31,6 +37,117 @@
     const DEP_COUNT = 0
     const installCmd = $derived(`npm i ${PKG_NAME}`)
     let copied = $state(false)
+    const demoCapacity = 6
+    const demoTtl = 300_000
+    const demoSpring: MotionTransition = {
+        type: 'spring',
+        stiffness: 360,
+        damping: 24,
+        mass: 0.8
+    }
+
+    type DemoEntry = {
+        key: string
+        value: string
+        rank: number
+    }
+
+    function createDemoCache() {
+        const nextCache = new MemoryCache<string>({ maxSize: demoCapacity, ttl: demoTtl })
+        nextCache.set('user:1', 'Ada')
+        nextCache.set('user:2', 'Grace')
+        nextCache.set('config', 'prod')
+        nextCache.set('session', 'warm')
+        return nextCache
+    }
+
+    function readDemoEntries(nextCache: MemoryCache<string>) {
+        return nextCache.entries().map(([key, value], index) => ({
+            key,
+            value: value ?? 'undefined',
+            rank: index + 1
+        }))
+    }
+
+    const initialDemoCache = createDemoCache()
+    let demoCache = $state(initialDemoCache)
+    let demoEntries = $state(readDemoEntries(initialDemoCache))
+    let demoHits = $state(0)
+    let demoMisses = $state(0)
+    let demoSets = $state(0)
+    let demoEvictions = $state(0)
+    let demoNextId = $state(3)
+    let demoLastOp = $state<'seed' | 'hit' | 'miss' | 'set' | 'evict'>('seed')
+    let demoLastKey = $state('session')
+    let demoLastValue = $state('warm')
+    let demoLastEvicted = $state('none')
+
+    let demoRequests = $derived(demoHits + demoMisses)
+    let demoHitRate = $derived(demoRequests > 0 ? Math.round((demoHits / demoRequests) * 100) : 100)
+    let demoLruKey = $derived(demoEntries[0]?.key ?? 'none')
+    let demoMruKey = $derived(demoEntries.at(-1)?.key ?? 'none')
+    let demoStatus = $derived(demoLastOp === 'miss' ? 'miss' : 'ready')
+
+    function syncDemoEntries() {
+        demoEntries = readDemoEntries(demoCache)
+    }
+
+    function runDemoHit() {
+        const key = demoEntries.at(-1)?.key ?? demoEntries[0]?.key
+        if (!key) return
+
+        const value = demoCache.get(key)
+        demoHits += 1
+        demoLastOp = 'hit'
+        demoLastKey = key
+        demoLastValue = value ?? 'undefined'
+        syncDemoEntries()
+    }
+
+    function runDemoMiss() {
+        const key = `ghost:${demoMisses + 1}`
+        demoCache.get(key)
+        demoMisses += 1
+        demoLastOp = 'miss'
+        demoLastKey = key
+        demoLastValue = 'undefined'
+        syncDemoEntries()
+    }
+
+    function runDemoSet() {
+        const key = `item:${demoNextId}`
+        const value = `value ${demoNextId}`
+        const isNewKey = !demoCache.has(key)
+
+        if (isNewKey && demoCache.size() >= demoCapacity) {
+            demoLastEvicted = demoCache.keys()[0] ?? 'none'
+            demoEvictions += 1
+            demoLastOp = 'evict'
+        } else {
+            demoLastOp = 'set'
+        }
+
+        demoCache.set(key, value)
+        demoSets += 1
+        demoNextId += 1
+        demoLastKey = key
+        demoLastValue = value
+        syncDemoEntries()
+    }
+
+    function resetDemo() {
+        demoCache = createDemoCache()
+        demoEntries = readDemoEntries(demoCache)
+        demoHits = 0
+        demoMisses = 0
+        demoSets = 0
+        demoEvictions = 0
+        demoNextId = 3
+        demoLastOp = 'seed'
+        demoLastKey = 'session'
+        demoLastValue = 'warm'
+        demoLastEvicted = 'none'
+    }
 
     interface StatItem {
         k: string
@@ -93,18 +210,15 @@
         },
         {
             title: 'TypeScript First',
-            description:
-                'Full type safety with generics. Your cached values are properly typed.',
+            description: 'Full type safety with generics. Your cached values are properly typed.',
             icon: FileCode
         },
         {
             title: 'Zero Dependencies',
-            description:
-                'Lightweight and self-contained. No bloat, no supply chain risks.',
+            description: 'Lightweight and self-contained. No bloat, no supply chain risks.',
             icon: Feather
         }
     ]
-
 </script>
 
 <div class="brut-wrap flex min-h-svh flex-col">
@@ -202,6 +316,138 @@
                     </div>
                 {/each}
             </section>
+
+            <section class="brut-demo">
+                <div class="lede">
+                    <div class="k">FIG-002 / CACHE</div>
+                    <h2>cache with <span>live telemetry</span>.</h2>
+                    <p>
+                        Drive a bounded <code>MemoryCache</code> and watch hits, misses, LRU order, and
+                        eviction pressure update against the same in-memory store.
+                    </p>
+                </div>
+                <div class="panel">
+                    <div class="bar">
+                        <span><span class="lbl">file</span> · <span class="v">cache.ts</span></span>
+                        <span
+                            ><span class="lbl">hit</span>
+                            <span class="v">{demoHitRate}%</span></span
+                        >
+                        <span
+                            ><span class="lbl">size</span>
+                            <span class="v">{demoEntries.length}/{demoCapacity}</span></span
+                        >
+                        <span
+                            ><span class="lbl">last</span> <span class="v">{demoLastOp}</span></span
+                        >
+                        <span class="live">
+                            {#if demoStatus === 'miss'}● MISS{:else}○ READY{/if}
+                        </span>
+                        <button class="ctrl" type="button" onclick={resetDemo}>↻ reset store</button
+                        >
+                    </div>
+                    <div class="stage">
+                        <section class="operation-panel" aria-label="Cache demo controls">
+                            <div class="operation-card">
+                                <span>operation</span>
+                                <strong>{demoLastOp}</strong>
+                                <p>
+                                    last key · <code>{demoLastKey}</code>
+                                </p>
+                            </div>
+
+                            <div class="operation-grid">
+                                <MotionButton
+                                    type="button"
+                                    onclick={runDemoHit}
+                                    whileTap={{ scale: 0.96 }}
+                                    transition={demoSpring}
+                                >
+                                    get hit
+                                </MotionButton>
+                                <MotionButton
+                                    type="button"
+                                    onclick={runDemoMiss}
+                                    whileTap={{ scale: 0.96 }}
+                                    transition={demoSpring}
+                                >
+                                    get miss
+                                </MotionButton>
+                                <MotionButton
+                                    type="button"
+                                    onclick={runDemoSet}
+                                    whileTap={{ scale: 0.96 }}
+                                    transition={demoSpring}
+                                >
+                                    set item
+                                </MotionButton>
+                            </div>
+
+                            <div class="result-card" class:miss={demoLastOp === 'miss'}>
+                                <span>result</span>
+                                <strong>{demoLastValue}</strong>
+                            </div>
+                        </section>
+
+                        <section
+                            class="cache-panel"
+                            aria-label="Cache entries ordered from LRU to MRU"
+                        >
+                            <div class="cache-head">
+                                <div>rank</div>
+                                <div>key</div>
+                                <div>value</div>
+                                <div>state</div>
+                            </div>
+
+                            <div class="cache-list">
+                                {#each demoEntries as entry (entry.key)}
+                                    <div
+                                        class="cache-row {entry.key === demoLruKey
+                                            ? 'lru'
+                                            : ''} {entry.key === demoMruKey ? 'mru' : ''}"
+                                    >
+                                        <div>{String(entry.rank).padStart(2, '0')}</div>
+                                        <code>{entry.key}</code>
+                                        <code>{entry.value}</code>
+                                        <div>
+                                            {#if entry.key === demoLruKey}
+                                                LRU
+                                            {:else if entry.key === demoMruKey}
+                                                MRU
+                                            {:else}
+                                                warm
+                                            {/if}
+                                        </div>
+                                    </div>
+                                {/each}
+
+                                {#each Array.from({ length: demoCapacity - demoEntries.length }, (_, i) => i) as slot (slot)}
+                                    <div class="cache-row empty">
+                                        <div>
+                                            {String(demoEntries.length + slot + 1).padStart(2, '0')}
+                                        </div>
+                                        <code>empty</code>
+                                        <code>slot</code>
+                                        <div>open</div>
+                                    </div>
+                                {/each}
+                            </div>
+                        </section>
+                    </div>
+                    <div class="footer">
+                        <div>hits · <span class="v">{demoHits}</span></div>
+                        <div>
+                            misses · <span class="v {demoLastOp === 'miss' ? 'danger' : ''}"
+                                >{demoMisses}</span
+                            >
+                        </div>
+                        <div>evictions · <span class="v">{demoEvictions}</span></div>
+                        <div>evicted · <span class="v">{demoLastEvicted}</span></div>
+                        <div>status · <span class="v accent">{demoStatus}</span></div>
+                    </div>
+                </div>
+            </section>
         </main>
 
         <!-- Features Section -->
@@ -255,7 +501,9 @@
             <div class="container mx-auto max-w-4xl">
                 <div class="mb-8 text-center">
                     <h2 class="mb-4 text-3xl font-bold text-foreground">Quick Example</h2>
-                    <p class="text-muted-foreground">Get started in seconds with simple, intuitive APIs.</p>
+                    <p class="text-muted-foreground">
+                        Get started in seconds with simple, intuitive APIs.
+                    </p>
                 </div>
                 <div class="overflow-hidden rounded-xl border border-border">
                     <!-- Toolbar -->
@@ -268,8 +516,7 @@
                                 <div class="h-3 w-3 rounded-full bg-yellow-400/60"></div>
                                 <div class="h-3 w-3 rounded-full bg-green-400/60"></div>
                             </div>
-                            <span class="text-xs font-medium text-muted-foreground"
-                                >example.ts</span
+                            <span class="text-xs font-medium text-muted-foreground">example.ts</span
                             >
                         </div>
                         <a
@@ -282,25 +529,39 @@
                     </div>
                     <!-- Code -->
                     <div class="bg-code-block-background p-6 font-mono text-sm">
-                        <pre class="text-code-block-foreground"><code><span class="text-brand-500">import</span> {'{'} MemoryCache, cached {'}'} <span class="text-brand-500">from</span> <span class="text-green-500">'@humanspeak/memory-cache'</span>
+                        <pre class="text-code-block-foreground"><code
+                                ><span class="text-brand-500">import</span
+                                > {'{'} MemoryCache, cached {'}'} <span class="text-brand-500"
+                                    >from</span
+                                > <span class="text-green-500">'@humanspeak/memory-cache'</span>
 
 <span class="text-muted-foreground">// Create a cache with 5 minute TTL and max 100 items</span>
-<span class="text-brand-500">const</span> cache = <span class="text-brand-500">new</span> MemoryCache&lt;<span class="text-yellow-500">User</span>&gt;({'{'}
+<span class="text-brand-500">const</span> cache = <span class="text-brand-500">new</span
+                                > MemoryCache&lt;<span class="text-yellow-500">User</span>&gt;({'{'}
     ttl: <span class="text-orange-500">300000</span>,
     maxSize: <span class="text-orange-500">100</span>
 {'}'})
 
 <span class="text-muted-foreground">// Simple get/set operations</span>
-cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span class="text-green-500">'Alice'</span> {'}'})
-<span class="text-brand-500">const</span> user = cache.get(<span class="text-green-500">'user:123'</span>)
+cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span class="text-green-500"
+                                    >'Alice'</span
+                                > {'}'})
+<span class="text-brand-500">const</span> user = cache.get(<span class="text-green-500"
+                                    >'user:123'</span
+                                >)
 
 <span class="text-muted-foreground">// Or use the @cached decorator</span>
 <span class="text-brand-500">class</span> <span class="text-yellow-500">UserService</span> {'{'}
-    <span class="text-purple-500">@cached</span>({'{'} ttl: <span class="text-orange-500">60000</span> {'}'})
-    <span class="text-brand-500">async</span> getUser(id: <span class="text-yellow-500">string</span>) {'{'}
-        <span class="text-brand-500">return</span> <span class="text-brand-500">await</span> fetchUserFromDb(id)
+    <span class="text-purple-500">@cached</span>({'{'} ttl: <span class="text-orange-500"
+                                    >60000</span
+                                > {'}'})
+    <span class="text-brand-500">async</span> getUser(id: <span class="text-yellow-500">string</span
+                                >) {'{'}
+        <span class="text-brand-500">return</span> <span class="text-brand-500">await</span
+                                > fetchUserFromDb(id)
     {'}'}
-{'}'}</code></pre>
+{'}'}</code
+                            ></pre>
                     </div>
                 </div>
             </div>
@@ -617,12 +878,315 @@ cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span clas
         content: attr(data-idx);
     }
 
+    .brut-demo {
+        display: grid;
+        grid-template-columns: minmax(260px, 0.22fr) minmax(0, 1fr);
+        gap: 24px;
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 28px 24px;
+    }
+
+    .brut-demo .lede .k {
+        color: var(--brut-ink-3);
+        font-size: 10.5px;
+        letter-spacing: 0.14em;
+        text-transform: uppercase;
+    }
+
+    .brut-demo .lede h2 {
+        margin: 20px 0 18px;
+        color: var(--brut-ink);
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-size: clamp(30px, 3vw, 42px);
+        font-weight: 700;
+        line-height: 1.05;
+        letter-spacing: 0;
+        overflow-wrap: anywhere;
+    }
+
+    .brut-demo .lede h2 span {
+        color: var(--brut-accent);
+    }
+
+    .brut-demo .lede p {
+        margin: 0;
+        color: var(--brut-ink-2);
+        font-family: 'Inter Variable', 'Inter', system-ui, sans-serif;
+        font-size: 15px;
+        line-height: 1.5;
+    }
+
+    .brut-demo .lede code {
+        border: 1px solid var(--brut-rule);
+        background: var(--brut-bg-2);
+        color: var(--brut-ink);
+        padding: 0 4px;
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-size: 13px;
+    }
+
+    .brut-demo .panel {
+        min-width: 0;
+        border: 1px solid var(--brut-rule);
+        background: var(--brut-bg);
+    }
+
+    .brut-demo .panel .bar {
+        display: flex;
+        align-items: center;
+        gap: 18px;
+        flex-wrap: wrap;
+        border-bottom: 1px solid var(--brut-rule);
+        background: var(--brut-bg-2);
+        color: var(--brut-ink-2);
+        padding: 8px 14px;
+        font-size: 11px;
+    }
+
+    .brut-demo .panel .bar .lbl {
+        color: var(--brut-ink-3);
+    }
+
+    .brut-demo .panel .bar .v {
+        color: var(--brut-ink);
+    }
+
+    .brut-demo .panel .bar .live {
+        margin-left: auto;
+        color: var(--brut-accent);
+    }
+
+    .brut-demo .panel .ctrl {
+        border: 1px solid var(--brut-rule);
+        background: transparent;
+        color: var(--brut-ink-2);
+        padding: 4px 10px;
+        font-family: inherit;
+        font-size: 11px;
+        cursor: pointer;
+    }
+
+    .brut-demo .panel .ctrl:hover {
+        background: var(--brut-bg);
+        color: var(--brut-ink);
+    }
+
+    .brut-demo .panel .stage {
+        display: grid;
+        grid-template-columns: minmax(280px, 0.78fr) minmax(420px, 1.22fr);
+        min-height: 404px;
+        align-items: stretch;
+        overflow: hidden;
+        background: var(--brut-bg);
+    }
+
+    .brut-demo .panel .operation-panel {
+        display: flex;
+        min-width: 0;
+        flex-direction: column;
+        border-right: 1px solid var(--brut-rule);
+        background: color-mix(in srgb, var(--brut-bg-2) 55%, var(--brut-bg));
+    }
+
+    .brut-demo .panel .operation-card,
+    .brut-demo .panel .result-card {
+        display: grid;
+        gap: 10px;
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 22px;
+    }
+
+    .brut-demo .panel .operation-card span,
+    .brut-demo .panel .result-card span {
+        color: var(--brut-accent);
+        font-size: 11px;
+        text-transform: uppercase;
+    }
+
+    .brut-demo .panel .operation-card strong,
+    .brut-demo .panel .result-card strong {
+        overflow: hidden;
+        color: var(--brut-ink);
+        font-size: 40px;
+        line-height: 1;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    .brut-demo .panel .operation-card p {
+        margin: 0;
+        color: var(--brut-ink-2);
+        font-size: 12px;
+    }
+
+    .brut-demo .panel .operation-card code {
+        border: 1px solid var(--brut-rule);
+        background: var(--brut-bg);
+        color: var(--brut-ink);
+        padding: 1px 5px;
+    }
+
+    .brut-demo .panel .result-card {
+        margin-top: auto;
+        border-top: 1px solid var(--brut-rule);
+        border-bottom: 0;
+    }
+
+    .brut-demo .panel .result-card.miss strong {
+        color: #dc2626;
+    }
+
+    .brut-demo .panel .operation-grid {
+        display: grid;
+        grid-template-columns: 1fr;
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .brut-demo .panel .operation-grid :global(button) {
+        min-height: 54px;
+        border: 0;
+        border-bottom: 1px solid var(--brut-rule);
+        border-radius: 0;
+        background: var(--brut-bg);
+        color: var(--brut-accent);
+        padding: 10px 14px;
+        font-family: inherit;
+        font-size: 13px;
+        text-align: left;
+        cursor: pointer;
+    }
+
+    .brut-demo .panel .operation-grid :global(button:last-child) {
+        border-bottom: 0;
+    }
+
+    .brut-demo .panel .operation-grid :global(button:hover) {
+        background: var(--brut-bg-2);
+    }
+
+    .brut-demo .panel .cache-panel {
+        display: flex;
+        min-width: 0;
+        min-height: 0;
+        flex-direction: column;
+    }
+
+    .brut-demo .panel .cache-head,
+    .brut-demo .panel :global(.cache-row),
+    .brut-demo .panel .cache-row {
+        display: grid;
+        grid-template-columns: 82px minmax(120px, 1fr) minmax(120px, 1fr) 100px;
+        align-items: center;
+        border-bottom: 1px solid var(--brut-rule);
+    }
+
+    .brut-demo .panel .cache-head {
+        background: var(--brut-bg-2);
+        color: var(--brut-ink-3);
+        font-size: 11px;
+        text-transform: uppercase;
+    }
+
+    .brut-demo .panel .cache-head div,
+    .brut-demo .panel :global(.cache-row > div),
+    .brut-demo .panel :global(.cache-row > code),
+    .brut-demo .panel .cache-row > div,
+    .brut-demo .panel .cache-row > code {
+        min-width: 0;
+        overflow: hidden;
+        border-right: 1px solid var(--brut-rule);
+        padding: 14px;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    .brut-demo .panel .cache-head div:last-child,
+    .brut-demo .panel :global(.cache-row > div:last-child),
+    .brut-demo .panel .cache-row > div:last-child {
+        border-right: 0;
+    }
+
+    .brut-demo .panel .cache-list {
+        display: grid;
+        grid-auto-rows: 58px;
+        min-height: 0;
+        flex: 1;
+        overflow: auto;
+    }
+
+    .brut-demo .panel :global(.cache-row),
+    .brut-demo .panel .cache-row {
+        min-height: 58px;
+        background: var(--brut-bg);
+        color: var(--brut-ink);
+        font-size: 12px;
+    }
+
+    .brut-demo .panel :global(.cache-row:nth-child(even)),
+    .brut-demo .panel .cache-row:nth-child(even) {
+        background: color-mix(in srgb, var(--brut-bg-2) 42%, var(--brut-bg));
+    }
+
+    .brut-demo .panel :global(.cache-row.lru) {
+        background: color-mix(in srgb, #dc2626 8%, var(--brut-bg));
+    }
+
+    .brut-demo .panel :global(.cache-row.mru) {
+        background: color-mix(in srgb, var(--brut-accent) 9%, var(--brut-bg));
+    }
+
+    .brut-demo .panel .cache-row.empty {
+        color: var(--brut-ink-3);
+        opacity: 0.75;
+    }
+
+    .brut-demo .panel :global(.cache-row code),
+    .brut-demo .panel .cache-row code {
+        color: var(--brut-ink);
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-weight: 700;
+    }
+
+    .brut-demo .panel .footer {
+        display: grid;
+        grid-template-columns: repeat(5, minmax(0, 1fr));
+        border-top: 1px solid var(--brut-rule);
+        color: var(--brut-ink-2);
+        font-size: 11px;
+    }
+
+    .brut-demo .panel .footer > div {
+        min-width: 0;
+        overflow: hidden;
+        border-right: 1px solid var(--brut-rule);
+        padding: 8px 14px;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+
+    .brut-demo .panel .footer > div:last-child {
+        border-right: 0;
+    }
+
+    .brut-demo .panel .footer .v {
+        color: var(--brut-ink);
+    }
+
+    .brut-demo .panel .footer .v.accent {
+        color: var(--brut-accent);
+    }
+
+    .brut-demo .panel .footer .v.danger {
+        color: #dc2626;
+    }
+
     @media (max-width: 720px) {
         .brut-coord {
             display: none;
         }
 
-        .brut-hero {
+        .brut-hero,
+        .brut-demo {
             grid-template-columns: 1fr;
             padding: 56px 16px 32px;
         }
@@ -639,5 +1203,57 @@ cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span clas
         .brut-stats .s .v {
             font-size: 44px;
         }
+
+        .brut-demo .panel .stage {
+            grid-template-columns: 1fr;
+            min-height: 0;
+        }
+
+        .brut-demo .panel .bar .live {
+            margin-left: 0;
+        }
+
+        .brut-demo .panel .operation-panel {
+            border-right: 0;
+            border-bottom: 1px solid var(--brut-rule);
+        }
+
+        .brut-demo .panel .operation-grid {
+            grid-template-columns: repeat(3, minmax(0, 1fr));
+        }
+
+        .brut-demo .panel .operation-grid :global(button) {
+            border-right: 1px solid var(--brut-rule);
+            border-bottom: 0;
+            padding-right: 8px;
+            padding-left: 8px;
+            text-align: center;
+        }
+
+        .brut-demo .panel .operation-grid :global(button:last-child) {
+            border-right: 0;
+        }
+
+        .brut-demo .panel .cache-head,
+        .brut-demo .panel :global(.cache-row),
+        .brut-demo .panel .cache-row {
+            grid-template-columns: 58px minmax(92px, 1fr) minmax(92px, 1fr) 74px;
+        }
+
+        .brut-demo .panel .cache-head div,
+        .brut-demo .panel :global(.cache-row > div),
+        .brut-demo .panel :global(.cache-row > code),
+        .brut-demo .panel .cache-row > div,
+        .brut-demo .panel .cache-row > code {
+            padding: 11px 8px;
+        }
+
+        .brut-demo .panel .footer {
+            grid-template-columns: repeat(2, minmax(0, 1fr));
+        }
+
+        .brut-demo .panel .footer > div {
+            border-bottom: 1px solid var(--brut-rule);
+        }
     }
 </style>

From 123a2500118775a1031fd47539a110bfaaf3220c Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 12:32:13 -0400
Subject: [PATCH 19/22] fix(docs): use hash csp for inline scripts

---
 docs/svelte.config.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/svelte.config.js b/docs/svelte.config.js
index 4980254..698e2c8 100644
--- a/docs/svelte.config.js
+++ b/docs/svelte.config.js
@@ -42,9 +42,10 @@ const config = {
     kit: {
         adapter: adapter(),
         csp: {
+            mode: 'hash',
             directives: {
                 'default-src': ['self'],
-                'script-src': ['self', 'nonce-%sveltekit.nonce%', 'https://analytics.ahrefs.com'],
+                'script-src': ['self', 'https://analytics.ahrefs.com', 'unsafe-inline'],
                 'style-src': ['self', 'unsafe-inline'],
                 'img-src': ['self', 'data:'],
                 'font-src': ['self'],

From beedd6760269f67d79cf2c5cb80251189aed702a Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 12:32:46 -0400
Subject: [PATCH 20/22] feat(docs): match upstream why section

---
 docs/src/routes/+page.svelte | 219 ++++++++++++++++++++++++-----------
 1 file changed, 152 insertions(+), 67 deletions(-)

diff --git a/docs/src/routes/+page.svelte b/docs/src/routes/+page.svelte
index 48e7269..1796de5 100644
--- a/docs/src/routes/+page.svelte
+++ b/docs/src/routes/+page.svelte
@@ -10,13 +10,6 @@
         type MotionTransition
     } from '@humanspeak/svelte-motion'
     import ArrowRight from '@lucide/svelte/icons/arrow-right'
-    import AtSign from '@lucide/svelte/icons/at-sign'
-    import Clock from '@lucide/svelte/icons/clock'
-    import Feather from '@lucide/svelte/icons/feather'
-    import FileCode from '@lucide/svelte/icons/file-code'
-    import Layers from '@lucide/svelte/icons/layers'
-    import Zap from '@lucide/svelte/icons/zap'
-    import type { Component } from 'svelte'
     import type { PageData } from './$types'
 
     const { data }: { data: PageData } = $props()
@@ -183,40 +176,30 @@
         setTimeout(() => (copied = false), 1500)
     }
 
-    const features: { title: string; description: string; icon: Component }[] = [
+    const features = [
         {
             title: 'Lightning Fast',
-            description:
-                'In-memory storage with O(1) lookups. No network latency, no disk I/O—just pure speed.',
-            icon: Zap
+            body: 'In-memory storage with O(1) lookups. No network latency, no disk I/O — just pure speed.'
         },
         {
             title: 'TTL Expiration',
-            description:
-                'Set time-to-live for cache entries. Expired items are automatically cleaned up.',
-            icon: Clock
+            body: 'Set time-to-live for cache entries. Expired items are automatically cleaned up when they age out.'
         },
         {
             title: 'LRU Eviction',
-            description:
-                'Smart eviction policy removes least recently used items when the cache reaches max size.',
-            icon: Layers
+            body: 'Smart eviction policy removes least recently used items when the cache reaches max size.'
         },
         {
             title: '@cached Decorator',
-            description:
-                'Automatic method-level caching with a simple decorator. No boilerplate required.',
-            icon: AtSign
+            body: 'Automatic method-level caching with a simple decorator. No boilerplate required.'
         },
         {
             title: 'TypeScript First',
-            description: 'Full type safety with generics. Your cached values are properly typed.',
-            icon: FileCode
+            body: 'Full type safety with generics. Cached values stay properly typed from write to read.'
         },
         {
             title: 'Zero Dependencies',
-            description: 'Lightweight and self-contained. No bloat, no supply chain risks.',
-            icon: Feather
+            body: 'Lightweight and self-contained. No bloat, no runtime dependency chain to audit.'
         }
     ]
 </script>
@@ -450,49 +433,27 @@
             </section>
         </main>
 
-        <!-- Features Section -->
-        <section class="relative px-6 py-10">
-            <div class="container mx-auto max-w-7xl">
-                <div class="mb-16 text-center">
-                    <h2
-                        class="mb-4 bg-gradient-to-r from-brand-500 to-brand-600 bg-clip-text text-4xl font-bold text-transparent md:text-5xl"
-                    >
-                        Why Memory Cache
-                    </h2>
-                    <p class="mx-auto max-w-2xl text-lg text-muted-foreground">
-                        Simple, fast, and reliable caching for your TypeScript applications.
-                    </p>
-                </div>
-                <div class="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
-                    {#each features as feature}
-                        {@const FeatureIcon = feature.icon}
-                        <div
-                            class="group relative overflow-hidden rounded-xl border border-border bg-card p-6 transition-all duration-300 hover:-translate-y-1 hover:border-brand-500/50 hover:shadow-lg hover:shadow-brand-500/10"
-                        >
-                            <div
-                                class="absolute inset-0 bg-gradient-to-br from-brand-500/5 to-transparent opacity-0 transition-opacity duration-300 group-hover:opacity-100"
-                            ></div>
-                            <div class="relative z-10">
-                                <div
-                                    class="mb-4 flex h-12 w-12 items-center justify-center rounded-lg bg-gradient-to-br from-brand-500 to-brand-600 text-white"
-                                >
-                                    <FeatureIcon size={20} />
-                                </div>
-                                <h3
-                                    class="mb-2 text-xl font-semibold transition-colors group-hover:text-brand-600"
-                                >
-                                    {feature.title}
-                                </h3>
-                                <p class="text-sm leading-relaxed text-muted-foreground">
-                                    {feature.description}
-                                </p>
-                            </div>
-                            <div
-                                class="absolute top-0 right-0 h-20 w-20 rounded-bl-full bg-gradient-to-bl from-brand-500/10 to-transparent opacity-0 transition-opacity duration-300 group-hover:opacity-100"
-                            ></div>
+        <section class="brut-feat">
+            <div class="lede">
+                <div class="k">FIG-003 / WHY US</div>
+                <h2>why <span>memory cache</span>.</h2>
+                <p>Simple, fast, and reliable caching for your TypeScript applications.</p>
+            </div>
+            <div class="grid">
+                {#each features as f, i (f.title)}
+                    <div class="cell">
+                        <div class="id">
+                            № {String(i + 1).padStart(2, '0')} / {String(features.length).padStart(
+                                2,
+                                '0'
+                            )}
                         </div>
-                    {/each}
-                </div>
+                        <div class="corner">▢</div>
+                        <h3>{f.title}</h3>
+                        <p>{f.body}</p>
+                        <div class="marker"></div>
+                    </div>
+                {/each}
             </div>
         </section>
 
@@ -1180,13 +1141,133 @@ cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span clas
         color: #dc2626;
     }
 
+    .brut-feat {
+        display: grid;
+        grid-template-columns: 220px 1fr;
+        gap: 24px;
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 28px 24px;
+    }
+
+    .brut-feat .lede .k {
+        color: var(--brut-ink-3);
+        font-size: 10.5px;
+        letter-spacing: 0.14em;
+        text-transform: uppercase;
+    }
+
+    .brut-feat .lede h2 {
+        margin: 20px 0 18px;
+        color: var(--brut-ink);
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-size: clamp(30px, 4vw, 46px);
+        font-weight: 700;
+        line-height: 1.05;
+        letter-spacing: 0;
+    }
+
+    .brut-feat .lede h2 span {
+        color: var(--brut-accent);
+    }
+
+    .brut-feat .lede p {
+        margin: 0;
+        color: var(--brut-ink-2);
+        font-family: 'Inter Variable', 'Inter', system-ui, sans-serif;
+        font-size: 15px;
+        line-height: 1.5;
+    }
+
+    .brut-feat .grid {
+        display: grid;
+        grid-template-columns: repeat(3, 1fr);
+        gap: 0;
+        border-top: 1px solid var(--brut-rule);
+        border-left: 1px solid var(--brut-rule);
+    }
+
+    .brut-feat .cell {
+        position: relative;
+        min-height: 200px;
+        border-right: 1px solid var(--brut-rule);
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 20px 22px;
+    }
+
+    .brut-feat .cell::after {
+        position: absolute;
+        inset: 8px;
+        border: 1px solid transparent;
+        content: '';
+        pointer-events: none;
+        transition: border-color 0.2s;
+    }
+
+    .brut-feat .cell:hover::after {
+        border-color: var(--brut-accent);
+    }
+
+    .brut-feat .cell .id {
+        color: var(--brut-ink-3);
+        font-size: 10.5px;
+        letter-spacing: 0.14em;
+    }
+
+    .brut-feat .cell h3 {
+        margin: 30px 0 8px;
+        color: var(--brut-ink);
+        font-family: 'Inter Variable', 'Inter', system-ui, sans-serif;
+        font-size: 22px;
+        font-weight: 500;
+        line-height: 1.15;
+        letter-spacing: 0;
+    }
+
+    .brut-feat .cell p {
+        max-width: 320px;
+        margin: 0;
+        color: var(--brut-ink-2);
+        font-family: 'Inter Variable', 'Inter', system-ui, sans-serif;
+        font-size: 13.5px;
+        line-height: 1.55;
+    }
+
+    .brut-feat .cell .corner {
+        position: absolute;
+        top: 14px;
+        right: 16px;
+        color: var(--brut-ink-3);
+        font-size: 10.5px;
+    }
+
+    .brut-feat .cell .marker {
+        position: absolute;
+        right: 16px;
+        bottom: 16px;
+        width: 14px;
+        height: 14px;
+        border: 1px solid var(--brut-ink-3);
+    }
+
+    .brut-feat .cell:nth-child(3n + 1) .marker {
+        border-color: var(--brut-accent);
+        background: var(--brut-accent);
+    }
+
+    @media (max-width: 1024px) {
+        .brut-feat .grid {
+            grid-template-columns: repeat(2, 1fr);
+        }
+    }
+
     @media (max-width: 720px) {
         .brut-coord {
             display: none;
         }
 
         .brut-hero,
-        .brut-demo {
+        .brut-demo,
+        .brut-feat {
             grid-template-columns: 1fr;
             padding: 56px 16px 32px;
         }
@@ -1255,5 +1336,9 @@ cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span clas
         .brut-demo .panel .footer > div {
             border-bottom: 1px solid var(--brut-rule);
         }
+
+        .brut-feat .grid {
+            grid-template-columns: 1fr;
+        }
     }
 </style>

From ca18c3ad3c2fcf535fd96365956ca4556d52f844 Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 13:15:20 -0400
Subject: [PATCH 21/22] feat(docs): add homepage llm section

---
 docs/src/routes/+page.svelte | 271 ++++++++++++++++++++++++++++++++++-
 1 file changed, 270 insertions(+), 1 deletion(-)

diff --git a/docs/src/routes/+page.svelte b/docs/src/routes/+page.svelte
index 1796de5..cc833ab 100644
--- a/docs/src/routes/+page.svelte
+++ b/docs/src/routes/+page.svelte
@@ -457,6 +457,69 @@
             </div>
         </section>
 
+        <section class="brut-ai" id="ai-ready">
+            <div class="lede">
+                <div class="k">FIG-004 / AI-READY</div>
+                <h2>built for <span>llm-assisted</span> code.</h2>
+                <p>
+                    Point Cursor, Claude Code, or any LLM at the manifests below and they know the
+                    Memory Cache API — constructor options, TTL behavior, LRU semantics, decorators,
+                    and examples.
+                </p>
+            </div>
+            <div class="ai-panel">
+                <div class="ai-head">
+                    <span class="ai-tab on">llms.txt</span>
+                    <span class="ai-tab">llms-full.txt</span>
+                    <span class="grow"></span>
+                    <span class="ai-meta">/llmstxt.org</span>
+                </div>
+                <div class="ai-grid">
+                    <a class="ai-cell" href="/llms.txt" target="_blank" rel="noopener">
+                        <div class="ai-cell-k">01 · index</div>
+                        <h3>
+                            <code>/llms.txt</code>
+                        </h3>
+                        <p>
+                            Compact map. Project blurb, feature list, API links, examples, and
+                            install commands. Drop into any agent for ground-truth lookup.
+                        </p>
+                        <div class="ai-cell-foot">~3.8 kB · open ↗</div>
+                    </a>
+                    <a class="ai-cell" href="/llms-full.txt" target="_blank" rel="noopener">
+                        <div class="ai-cell-k">02 · full</div>
+                        <h3>
+                            <code>/llms-full.txt</code>
+                        </h3>
+                        <p>
+                            Full reference. Every guide, API page, example, decorator note, TTL
+                            option, and LRU behavior — optimized for LLM context windows.
+                        </p>
+                        <div class="ai-cell-foot">~54.5 kB · open ↗</div>
+                    </a>
+                    <a class="ai-cell" href="/docs" target="_blank" rel="noopener">
+                        <div class="ai-cell-k">03 · per-page mirrors</div>
+                        <h3>
+                            <code>/docs/&lt;slug&gt;.md</code>
+                        </h3>
+                        <p>
+                            Every doc page mirrored as raw markdown. Append <code>.md</code> to any doc
+                            URL to fetch the source an agent can quote verbatim.
+                        </p>
+                        <div class="ai-cell-foot">14 docs · open ↗</div>
+                    </a>
+                </div>
+                <div class="ai-prompt">
+                    <span class="ai-prompt-k">// example prompt</span>
+                    <code
+                        >Use https://memory.svelte.page/llms.txt as the source for Memory Cache APIs.
+                        Add a <em>MemoryCache&lt;User&gt;</em> with five minute TTL, max size 100, and
+                        method-level caching with <em>@cached</em>.</code
+                    >
+                </div>
+            </div>
+        </section>
+
         <!-- Code Example Section -->
         <section class="relative px-6 py-10">
             <div class="container mx-auto max-w-4xl">
@@ -1254,10 +1317,204 @@ cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span clas
         background: var(--brut-accent);
     }
 
+    .brut-ai {
+        display: grid;
+        grid-template-columns: 220px 1fr;
+        gap: 24px;
+        border-bottom: 1px solid var(--brut-rule);
+        padding: 28px 24px;
+    }
+
+    .brut-ai .lede .k {
+        color: var(--brut-ink-3);
+        font-size: 10.5px;
+        letter-spacing: 0.14em;
+        text-transform: uppercase;
+    }
+
+    .brut-ai .lede h2 {
+        margin: 20px 0 18px;
+        color: var(--brut-ink);
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-size: clamp(30px, 4vw, 46px);
+        font-weight: 700;
+        line-height: 1.05;
+        letter-spacing: 0;
+    }
+
+    .brut-ai .lede h2 span {
+        color: var(--brut-accent);
+    }
+
+    .brut-ai .lede p {
+        margin: 0;
+        color: var(--brut-ink-2);
+        font-family: 'Inter Variable', 'Inter', system-ui, sans-serif;
+        font-size: 15px;
+        line-height: 1.5;
+    }
+
+    .brut-ai .ai-panel {
+        display: flex;
+        flex-direction: column;
+        border: 1px solid var(--brut-rule);
+        background: var(--brut-bg);
+    }
+
+    .brut-ai .ai-head {
+        display: flex;
+        align-items: center;
+        gap: 0;
+        border-bottom: 1px solid var(--brut-rule);
+        background: var(--brut-bg-2);
+        color: var(--brut-ink-3);
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-size: 11px;
+        letter-spacing: 0.14em;
+        text-transform: uppercase;
+    }
+
+    .brut-ai .ai-tab {
+        border-right: 1px solid var(--brut-rule);
+        padding: 9px 14px;
+    }
+
+    .brut-ai .ai-tab.on {
+        background: var(--brut-bg);
+        color: var(--brut-ink);
+    }
+
+    .brut-ai .grow {
+        flex: 1;
+    }
+
+    .brut-ai .ai-meta {
+        border-left: 1px solid var(--brut-rule);
+        padding: 9px 14px;
+    }
+
+    .brut-ai .ai-grid {
+        display: grid;
+        grid-template-columns: repeat(3, 1fr);
+    }
+
+    .brut-ai .ai-cell {
+        position: relative;
+        min-height: 200px;
+        border-right: 1px solid var(--brut-rule);
+        color: var(--brut-ink);
+        padding: 20px 22px 56px;
+        text-decoration: none;
+        transition: background-color 0.15s;
+    }
+
+    .brut-ai .ai-cell:last-child {
+        border-right: 0;
+    }
+
+    .brut-ai .ai-cell:hover {
+        background: color-mix(in oklab, var(--brut-accent) 6%, transparent);
+    }
+
+    .brut-ai .ai-cell-k {
+        color: var(--brut-ink-3);
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-size: 10.5px;
+        letter-spacing: 0.14em;
+        text-transform: uppercase;
+    }
+
+    .brut-ai .ai-cell h3 {
+        margin: 22px 0 10px;
+        color: var(--brut-ink);
+        font-family: 'Inter Variable', 'Inter', system-ui, sans-serif;
+        font-size: 22px;
+        font-weight: 500;
+        line-height: 1.15;
+        letter-spacing: 0;
+    }
+
+    .brut-ai .ai-cell h3 code {
+        background: transparent;
+        color: var(--brut-accent);
+        padding: 0;
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-size: 0.85em;
+    }
+
+    .brut-ai .ai-cell p {
+        margin: 0;
+        color: var(--brut-ink-2);
+        font-size: 13.5px;
+        line-height: 1.55;
+    }
+
+    .brut-ai .ai-cell p code {
+        border-radius: 2px;
+        background: var(--brut-bg-2);
+        padding: 1px 4px;
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-size: 0.92em;
+    }
+
+    .brut-ai .ai-cell-foot {
+        position: absolute;
+        bottom: 18px;
+        left: 22px;
+        color: var(--brut-ink-3);
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-size: 11px;
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+    }
+
+    .brut-ai .ai-prompt {
+        border-top: 1px solid var(--brut-rule);
+        background: var(--brut-bg-2);
+        color: var(--brut-ink-2);
+        padding: 16px 22px;
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-size: 13px;
+        line-height: 1.6;
+    }
+
+    .brut-ai .ai-prompt-k {
+        display: block;
+        margin-bottom: 6px;
+        color: var(--brut-ink-3);
+        font-size: 10.5px;
+        letter-spacing: 0.14em;
+        text-transform: uppercase;
+    }
+
+    .brut-ai .ai-prompt code {
+        background: transparent;
+        color: var(--brut-ink);
+        padding: 0;
+    }
+
+    .brut-ai .ai-prompt em {
+        color: var(--brut-accent);
+        font-style: normal;
+    }
+
     @media (max-width: 1024px) {
         .brut-feat .grid {
             grid-template-columns: repeat(2, 1fr);
         }
+
+        .brut-ai .ai-grid {
+            grid-template-columns: 1fr;
+        }
+
+        .brut-ai .ai-cell {
+            border-right: 0;
+            border-bottom: 1px solid var(--brut-rule);
+        }
+
+        .brut-ai .ai-cell:last-child {
+            border-bottom: 0;
+        }
     }
 
     @media (max-width: 720px) {
@@ -1267,7 +1524,8 @@ cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span clas
 
         .brut-hero,
         .brut-demo,
-        .brut-feat {
+        .brut-feat,
+        .brut-ai {
             grid-template-columns: 1fr;
             padding: 56px 16px 32px;
         }
@@ -1340,5 +1598,16 @@ cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span clas
         .brut-feat .grid {
             grid-template-columns: 1fr;
         }
+
+        .brut-ai .ai-head {
+            align-items: stretch;
+            flex-wrap: wrap;
+        }
+
+        .brut-ai .ai-meta {
+            width: 100%;
+            border-top: 1px solid var(--brut-rule);
+            border-left: 0;
+        }
     }
 </style>

From 05da0588be11d6048b57a5be0a05951612134979 Mon Sep 17 00:00:00 2001
From: Jason Kummerl <jason.h@kummerl.com>
Date: Wed, 3 Jun 2026 13:15:58 -0400
Subject: [PATCH 22/22] feat(docs): add upstream install footer

---
 docs/src/routes/+page.svelte | 190 ++++++++++++++++++++++-------------
 1 file changed, 121 insertions(+), 69 deletions(-)

diff --git a/docs/src/routes/+page.svelte b/docs/src/routes/+page.svelte
index cc833ab..ca9c1b1 100644
--- a/docs/src/routes/+page.svelte
+++ b/docs/src/routes/+page.svelte
@@ -9,7 +9,6 @@
         MotionSpan,
         type MotionTransition
     } from '@humanspeak/svelte-motion'
-    import ArrowRight from '@lucide/svelte/icons/arrow-right'
     import type { PageData } from './$types'
 
     const { data }: { data: PageData } = $props()
@@ -204,7 +203,7 @@
     ]
 </script>
 
-<div class="brut-wrap flex min-h-svh flex-col">
+<div id="top" class="brut-wrap flex min-h-svh flex-col">
     <Header />
     <div class="relative flex flex-1 flex-col overflow-hidden">
         <main class="brut">
@@ -520,74 +519,42 @@
             </div>
         </section>
 
-        <!-- Code Example Section -->
-        <section class="relative px-6 py-10">
-            <div class="container mx-auto max-w-4xl">
-                <div class="mb-8 text-center">
-                    <h2 class="mb-4 text-3xl font-bold text-foreground">Quick Example</h2>
-                    <p class="text-muted-foreground">
-                        Get started in seconds with simple, intuitive APIs.
-                    </p>
-                </div>
-                <div class="overflow-hidden rounded-xl border border-border">
-                    <!-- Toolbar -->
-                    <div
-                        class="flex items-center justify-between border-b border-border bg-card/80 px-4 py-2"
-                    >
-                        <div class="flex items-center gap-3">
-                            <div class="flex gap-1.5">
-                                <div class="h-3 w-3 rounded-full bg-red-400/60"></div>
-                                <div class="h-3 w-3 rounded-full bg-yellow-400/60"></div>
-                                <div class="h-3 w-3 rounded-full bg-green-400/60"></div>
-                            </div>
-                            <span class="text-xs font-medium text-muted-foreground">example.ts</span
-                            >
-                        </div>
-                        <a
-                            href="/docs/getting-started"
-                            class="inline-flex items-center gap-1 text-xs font-medium text-brand-600 transition-colors hover:text-brand-700"
+        <section class="brut-foot">
+            <div class="info">
+                <div>SET / JETBRAINS MONO + INTER</div>
+                <div>HUMANSPEAK · 2026</div>
+                <div>MIT LICENCE</div>
+                <div class="v">● {PKG_VERSION}</div>
+            </div>
+            <MotionButton
+                class="big"
+                type="button"
+                onclick={copyInstall}
+                aria-label="Copy install command"
+                whileTap={{ scale: 0.985 }}
+                whileHover={{ scale: 1.005 }}
+                transition={{ type: 'spring', stiffness: 280, damping: 22 }}
+            >
+                npm&nbsp;i<br /><span>@humanspeak/</span><br />memory-cache
+                <span class="copy-hint">
+                    <AnimatePresence initial={false}>
+                        <MotionSpan
+                            key={copied ? 'copied' : 'idle'}
+                            class="copy-hint-label"
+                            initial={{ opacity: 0, y: 8 }}
+                            animate={{ opacity: 1, y: 0 }}
+                            exit={{ opacity: 0, y: -8 }}
+                            transition={{ duration: 0.22, ease: 'easeOut' }}
                         >
-                            Get Started
-                            <ArrowRight size={12} />
-                        </a>
-                    </div>
-                    <!-- Code -->
-                    <div class="bg-code-block-background p-6 font-mono text-sm">
-                        <pre class="text-code-block-foreground"><code
-                                ><span class="text-brand-500">import</span
-                                > {'{'} MemoryCache, cached {'}'} <span class="text-brand-500"
-                                    >from</span
-                                > <span class="text-green-500">'@humanspeak/memory-cache'</span>
-
-<span class="text-muted-foreground">// Create a cache with 5 minute TTL and max 100 items</span>
-<span class="text-brand-500">const</span> cache = <span class="text-brand-500">new</span
-                                > MemoryCache&lt;<span class="text-yellow-500">User</span>&gt;({'{'}
-    ttl: <span class="text-orange-500">300000</span>,
-    maxSize: <span class="text-orange-500">100</span>
-{'}'})
-
-<span class="text-muted-foreground">// Simple get/set operations</span>
-cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span class="text-green-500"
-                                    >'Alice'</span
-                                > {'}'})
-<span class="text-brand-500">const</span> user = cache.get(<span class="text-green-500"
-                                    >'user:123'</span
-                                >)
-
-<span class="text-muted-foreground">// Or use the @cached decorator</span>
-<span class="text-brand-500">class</span> <span class="text-yellow-500">UserService</span> {'{'}
-    <span class="text-purple-500">@cached</span>({'{'} ttl: <span class="text-orange-500"
-                                    >60000</span
-                                > {'}'})
-    <span class="text-brand-500">async</span> getUser(id: <span class="text-yellow-500">string</span
-                                >) {'{'}
-        <span class="text-brand-500">return</span> <span class="text-brand-500">await</span
-                                > fetchUserFromDb(id)
-    {'}'}
-{'}'}</code
-                            ></pre>
-                    </div>
-                </div>
+                            {copied ? '✓ copied to clipboard' : 'click to copy'}
+                        </MotionSpan>
+                    </AnimatePresence>
+                </span>
+            </MotionButton>
+            <div class="info right">
+                <div>SHEET 04 / 04</div>
+                <div>END OF DOCUMENT</div>
+                <a class="v" href="#top">↩ TO TOP</a>
             </div>
         </section>
     </div>
@@ -1498,6 +1465,82 @@ cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span clas
         font-style: normal;
     }
 
+    .brut-foot {
+        display: grid;
+        grid-template-columns: 200px 1fr 200px;
+        align-items: end;
+        gap: 24px;
+        border-top: 1px solid var(--brut-rule);
+        padding: 60px 24px 36px;
+    }
+
+    .brut-foot :global(.big) {
+        position: relative;
+        border: 0;
+        background: transparent;
+        color: var(--brut-ink);
+        padding: 0;
+        font-family: 'JetBrains Mono Variable', 'JetBrains Mono', ui-monospace, monospace;
+        font-size: clamp(40px, 7vw, 96px);
+        line-height: 0.9;
+        letter-spacing: 0;
+        text-align: left;
+        text-transform: lowercase;
+        cursor: pointer;
+    }
+
+    .brut-foot :global(.big span) {
+        color: var(--brut-accent);
+    }
+
+    .brut-foot :global(.big .copy-hint) {
+        display: inline-grid;
+        align-items: center;
+        justify-items: start;
+        min-width: 200px;
+        height: 16px;
+        margin-top: 16px;
+        overflow: hidden;
+        color: var(--brut-ink-3);
+        font-size: 11px;
+        letter-spacing: 0.14em;
+        text-transform: uppercase;
+    }
+
+    .brut-foot :global(.big .copy-hint-label) {
+        display: inline-block;
+        grid-area: 1 / 1;
+        white-space: nowrap;
+        will-change: transform, opacity;
+    }
+
+    .brut-foot :global(.big:hover .copy-hint) {
+        color: var(--brut-accent);
+    }
+
+    .brut-foot .info {
+        color: var(--brut-ink-3);
+        font-size: 11px;
+        line-height: 1.8;
+        letter-spacing: 0.12em;
+    }
+
+    .brut-foot .info.right {
+        text-align: right;
+    }
+
+    .brut-foot .info .v,
+    .brut-foot .info a.v {
+        display: block;
+        margin-top: 12px;
+        color: var(--brut-ink);
+        text-decoration: none;
+    }
+
+    .brut-foot .info a.v:hover {
+        color: var(--brut-accent);
+    }
+
     @media (max-width: 1024px) {
         .brut-feat .grid {
             grid-template-columns: repeat(2, 1fr);
@@ -1609,5 +1652,14 @@ cache.set(<span class="text-green-500">'user:123'</span>, {'{'} name: <span clas
             border-top: 1px solid var(--brut-rule);
             border-left: 0;
         }
+
+        .brut-foot {
+            grid-template-columns: 1fr;
+            padding: 44px 16px 28px;
+        }
+
+        .brut-foot .info.right {
+            text-align: left;
+        }
     }
 </style>