From f82ad5992ff075814bc6e17395ac2385f4398e5a Mon Sep 17 00:00:00 2001
From: Bissbert <43237892+Bissbert@users.noreply.github.com>
Date: Tue, 5 May 2026 17:53:12 +0700
Subject: [PATCH 1/3] feat(seo): article dateModified + visible Last updated
 line

- LearnSchema accepts datePublished/dateModified and emits them in
  LearningResource+Article JSON-LD when present.
- learn/[...slug].astro derives dateModified from data.reviewedAt with
  a fall-back to source YAML mtime, then renders an unconditional
  "Last updated <time>" line in the article header for trust/E-E-A-T.
- sync-knowledge stamps each copied YAML with its git-commit timestamp
  so the mtime fall-back surfaces the real edit date instead of the
  build wall-clock time.
---
 scripts/sync-knowledge.ts            | 33 ++++++++++++++++++----
 src/components/seo/LearnSchema.astro | 10 +++++--
 src/pages/learn/[...slug].astro      | 41 ++++++++++++++++++++++------
 3 files changed, 68 insertions(+), 16 deletions(-)

diff --git a/scripts/sync-knowledge.ts b/scripts/sync-knowledge.ts
index 5c8e3fb..d09a624 100644
--- a/scripts/sync-knowledge.ts
+++ b/scripts/sync-knowledge.ts
@@ -5,7 +5,7 @@
  */
 
 import { execSync } from 'node:child_process';
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, utimesSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -32,7 +32,27 @@ function error(message: string) {
  * Recursively copy YAML files from source to destination,
  * preserving subdirectory structure (e.g., equipment/, species/, origin/)
  */
-function copyYamlFilesRecursive(sourceDir: string, destDir: string, relativePath: string = ''): number {
+/**
+ * Stamp dest with the source file's last git-commit timestamp so the build can
+ * surface a meaningful "Last updated" date instead of the sync wall-clock time.
+ * Falls back silently if the file is not tracked or git isn't available.
+ */
+function stampGitMtime(sourcePath: string, destPath: string, repoRoot: string): void {
+  try {
+    const isoStamp = execSync(`git log -1 --format=%cI -- "${sourcePath}"`, {
+      cwd: repoRoot,
+      encoding: 'utf-8',
+    }).trim();
+    if (!isoStamp) return;
+    const ts = new Date(isoStamp);
+    if (Number.isNaN(ts.getTime())) return;
+    utimesSync(destPath, ts, ts);
+  } catch {
+    // ignore — leaves cpSync's default mtime in place
+  }
+}
+
+function copyYamlFilesRecursive(sourceDir: string, destDir: string, relativePath: string = '', repoRoot?: string): number {
   let count = 0;
   const currentSource = join(sourceDir, relativePath);
   const currentDest = join(destDir, relativePath);
@@ -50,13 +70,16 @@ function copyYamlFilesRecursive(sourceDir: string, destDir: string, relativePath
 
     if (stat.isDirectory()) {
       // Recurse into subdirectory
-      count += copyYamlFilesRecursive(sourceDir, destDir, join(relativePath, entry));
+      count += copyYamlFilesRecursive(sourceDir, destDir, join(relativePath, entry), repoRoot);
     } else if (entry.endsWith('.yaml') || entry.endsWith('.yml')) {
       // Copy YAML file
       if (!existsSync(currentDest)) {
         mkdirSync(currentDest, { recursive: true });
       }
       cpSync(sourcePath, destPath);
+      if (repoRoot) {
+        stampGitMtime(sourcePath, destPath, repoRoot);
+      }
       const displayPath = relativePath ? `${relativePath}/${entry}` : entry;
       log(`  Copied: ${displayPath}`);
       count++;
@@ -82,7 +105,7 @@ function syncFromLocal(): boolean {
   }
 
   // Copy YAML files recursively (handles flat files and subdirectories)
-  const fileCount = copyYamlFilesRecursive(localSource, CONTENT_DEST);
+  const fileCount = copyYamlFilesRecursive(localSource, CONTENT_DEST, '', LOCAL_KNOWLEDGE_DIR);
 
   if (fileCount === 0) {
     log('No YAML files found in local source');
@@ -129,7 +152,7 @@ function syncFromGit(): boolean {
   }
 
   // Copy YAML files recursively (handles flat files and subdirectories)
-  const fileCount = copyYamlFilesRecursive(CONTENT_SOURCE, CONTENT_DEST);
+  const fileCount = copyYamlFilesRecursive(CONTENT_SOURCE, CONTENT_DEST, '', KNOWLEDGE_DIR);
 
   if (fileCount === 0) {
     log('No YAML files found in source');
diff --git a/src/components/seo/LearnSchema.astro b/src/components/seo/LearnSchema.astro
index 75c18cb..1dddf00 100644
--- a/src/components/seo/LearnSchema.astro
+++ b/src/components/seo/LearnSchema.astro
@@ -11,9 +11,13 @@ interface Props {
   subcategory?: string;
   difficulty?: string;
   slug: string;
+  /** ISO 8601 datetime — when the article was first published. */
+  datePublished?: string;
+  /** ISO 8601 datetime — when the article was last meaningfully updated. */
+  dateModified?: string;
 }
 
-const { title, description, category, subcategory, difficulty, slug } = Astro.props;
+const { title, description, category, subcategory, difficulty, slug, datePublished, dateModified } = Astro.props;
 const url = `https://gemmology.dev/learn/${slug}`;
 
 // Helper to format category names
@@ -57,7 +61,9 @@ const articleSchema = {
   "about": {
     "@type": "Thing",
     "name": formatName(category)
-  }
+  },
+  ...(datePublished ? { "datePublished": datePublished } : {}),
+  ...(dateModified ? { "dateModified": dateModified } : {}),
 };
 
 // Build breadcrumb from category/subcategory
diff --git a/src/pages/learn/[...slug].astro b/src/pages/learn/[...slug].astro
index 32ded3c..114ed26 100644
--- a/src/pages/learn/[...slug].astro
+++ b/src/pages/learn/[...slug].astro
@@ -1,4 +1,7 @@
 ---
+import { statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
 import { getCollection } from 'astro:content';
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import { Breadcrumb, PageNav } from '../../components/docs';
@@ -24,6 +27,29 @@ interface Props {
 const { entry, allEntries } = Astro.props;
 const { data } = entry;
 
+// Resolve dateModified for SEO + visible "Last updated" line.
+// Order of preference: explicit reviewedAt frontmatter → file mtime fallback.
+function resolveDateModified(): string {
+  if (data.reviewedAt) return data.reviewedAt;
+  try {
+    const filePath = (entry as unknown as { filePath?: string }).filePath;
+    if (filePath) {
+      const abs = filePath.startsWith('file:') ? fileURLToPath(filePath) : path.resolve(filePath);
+      return new Date(statSync(abs).mtimeMs).toISOString();
+    }
+  } catch {
+    // fall through
+  }
+  return new Date().toISOString();
+}
+
+const dateModified = resolveDateModified();
+const dateModifiedDisplay = new Date(dateModified).toLocaleDateString('en-GB', {
+  year: 'numeric',
+  month: 'long',
+  day: 'numeric',
+});
+
 // Helper to format category/subcategory names for display
 function formatCategoryName(name: string): string {
   return name
@@ -155,6 +181,7 @@ const pretestQuestions: WidgetQuestion[] = articleQuestions
     subcategory={data.subcategory}
     difficulty={data.difficulty}
     slug={entry.id}
+    dateModified={dateModified}
   />
   <Container size="md" padding="md">
     <Breadcrumb items={breadcrumbItems} />
@@ -168,15 +195,11 @@ const pretestQuestions: WidgetQuestion[] = articleQuestions
 
         <div class="mt-4 flex flex-wrap items-center gap-x-4 gap-y-2 text-sm text-slate-500">
           <span>By <a href="/about" class="text-crystal-700 underline underline-offset-2 decoration-crystal-300 hover:decoration-crystal-700">{data.author || 'gemmology.dev editors'}</a></span>
-          {data.reviewedAt && (
-            <span>
-              Last reviewed
-              <time datetime={data.reviewedAt}>
-                {new Date(data.reviewedAt).toLocaleDateString('en-GB', { year: 'numeric', month: 'long', day: 'numeric' })}
-              </time>
-              {data.reviewedBy && <span> by {data.reviewedBy}</span>}
-            </span>
-          )}
+          <span>
+            Last updated
+            <time datetime={dateModified}>{dateModifiedDisplay}</time>
+            {data.reviewedBy && <span> by {data.reviewedBy}</span>}
+          </span>
         </div>
 
         {data.tags && data.tags.length > 0 && (

From 6ca645e4a78783049f501a2668f976618d3d8e6a Mon Sep 17 00:00:00 2001
From: Bissbert <43237892+Bissbert@users.noreply.github.com>
Date: Tue, 5 May 2026 17:59:21 +0700
Subject: [PATCH 2/3] perf(gallery): SSG-render families, lazy-load sql.js on
 first filter

The gallery used to block its first paint on the 8 MB minerals.db +
sql.js wasm bundle. Now the family list and filter dropdowns are
fetched at build time via db-server and passed to the React Gallery
component as initial props.

- gallery/index.astro fetches getAllFamilies / getCrystalSystems /
  getOrigins / getMineralGroups during SSG.
- useFamilies / useFilters accept initial data and skip the wasm-DB
  fetch on mount when provided. Reset/clear-filter paths replay the
  cached SSG data instead of re-hitting the DB.
- sanitize-svg short-circuits on the server (no window) and trusts our
  own crystal-renderer SVG output during SSG.
- Adds getOrigins() to db-server.

Net: gallery ships in ~415 KB gzipped HTML with 12 cards visible
immediately; the 8 MB DB only downloads when the user actually filters
or searches.
---
 src/components/gallery/Gallery.tsx | 24 +++++++++++++++++++++---
 src/hooks/useCrystalDB.ts          | 29 ++++++++++++++++++++++-------
 src/hooks/useFamilies.ts           | 24 +++++++++++++++++++-----
 src/lib/db-server.ts               | 15 +++++++++++++++
 src/lib/sanitize-svg.ts            |  8 ++++++++
 src/pages/gallery/index.astro      | 20 ++++++++++++++++++++
 6 files changed, 105 insertions(+), 15 deletions(-)

diff --git a/src/components/gallery/Gallery.tsx b/src/components/gallery/Gallery.tsx
index f86cf58..758f307 100644
--- a/src/components/gallery/Gallery.tsx
+++ b/src/components/gallery/Gallery.tsx
@@ -5,16 +5,34 @@ import { Pagination } from '../ui/Pagination';
 import { useFamilies } from '../../hooks/useFamilies';
 import { useFilters } from '../../hooks/useCrystalDB';
 import { usePagination } from '../../hooks/usePagination';
+import type { MineralFamily } from '../../lib/db';
 
 interface GalleryProps {
   initialSystem?: string;
   initialSearch?: string;
   initialOrigin?: string;
+  /** SSG-fetched families — when present, the wasm DB only loads on filter/search. */
+  initialFamilies?: MineralFamily[];
+  initialSystems?: string[];
+  initialOrigins?: string[];
+  initialGroups?: string[];
 }
 
-export function Gallery({ initialSystem = '', initialSearch = '', initialOrigin = '' }: GalleryProps) {
-  const { families, loading, error, search, filterBySystem, filterByOrigin, filterByGroup } = useFamilies();
-  const { systems, origins, mineralGroups, loading: filtersLoading } = useFilters();
+export function Gallery({
+  initialSystem = '',
+  initialSearch = '',
+  initialOrigin = '',
+  initialFamilies,
+  initialSystems,
+  initialOrigins,
+  initialGroups,
+}: GalleryProps) {
+  const { families, loading, error, search, filterBySystem, filterByOrigin, filterByGroup } = useFamilies(initialFamilies);
+  const { systems, origins, mineralGroups, loading: filtersLoading } = useFilters({
+    systems: initialSystems,
+    origins: initialOrigins,
+    mineralGroups: initialGroups,
+  });
   const [searchQuery, setSearchQuery] = useState(initialSearch);
   const [selectedSystem, setSelectedSystem] = useState<string | null>(initialSystem || null);
   const [selectedOrigin, setSelectedOrigin] = useState<string | null>(initialOrigin || null);
diff --git a/src/hooks/useCrystalDB.ts b/src/hooks/useCrystalDB.ts
index 87b5b52..21ab3fd 100644
--- a/src/hooks/useCrystalDB.ts
+++ b/src/hooks/useCrystalDB.ts
@@ -149,14 +149,29 @@ interface UseFiltersResult {
   loading: boolean;
 }
 
-export function useFilters(): UseFiltersResult {
-  const [systems, setSystems] = useState<string[]>([]);
-  const [categories, setCategories] = useState<string[]>([]);
-  const [origins, setOrigins] = useState<string[]>([]);
-  const [mineralGroups, setMineralGroups] = useState<string[]>([]);
-  const [loading, setLoading] = useState(true);
+interface UseFiltersInitial {
+  systems?: string[];
+  categories?: string[];
+  origins?: string[];
+  mineralGroups?: string[];
+}
+
+/**
+ * When initial filter lists are provided (SSG case), skips the wasm-DB hit and
+ * serves the filter dropdowns synchronously.
+ */
+export function useFilters(initial: UseFiltersInitial = {}): UseFiltersResult {
+  const hasInitial = Boolean(
+    initial.systems || initial.categories || initial.origins || initial.mineralGroups,
+  );
+  const [systems, setSystems] = useState<string[]>(initial.systems ?? []);
+  const [categories, setCategories] = useState<string[]>(initial.categories ?? []);
+  const [origins, setOrigins] = useState<string[]>(initial.origins ?? []);
+  const [mineralGroups, setMineralGroups] = useState<string[]>(initial.mineralGroups ?? []);
+  const [loading, setLoading] = useState(!hasInitial);
 
   useEffect(() => {
+    if (hasInitial) return;
     (async () => {
       try {
         const [systemsData, categoriesData, originsData, groupsData] = await Promise.all([
@@ -175,7 +190,7 @@ export function useFilters(): UseFiltersResult {
         setLoading(false);
       }
     })();
-  }, []);
+  }, [hasInitial]);
 
   return { systems, categories, origins, mineralGroups, loading };
 }
diff --git a/src/hooks/useFamilies.ts b/src/hooks/useFamilies.ts
index 1eac073..5861252 100644
--- a/src/hooks/useFamilies.ts
+++ b/src/hooks/useFamilies.ts
@@ -1,4 +1,4 @@
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useEffect, useCallback, useRef } from 'react';
 import {
   getAllFamilies,
   getFamilyById,
@@ -27,13 +27,26 @@ interface UseFamiliesResult {
 /**
  * Hook for loading and filtering mineral families in the gallery.
  * Returns families with expression counts (no duplicates like the old minerals approach).
+ *
+ * When `initialFamilies` is provided (build-time SSG case), skips the initial
+ * sql.js fetch and serves them synchronously on first paint. The wasm DB only
+ * loads on the first dynamic action (search/filter).
  */
-export function useFamilies(): UseFamiliesResult {
-  const [families, setFamilies] = useState<MineralFamily[]>([]);
-  const [loading, setLoading] = useState(true);
+export function useFamilies(initialFamilies?: MineralFamily[]): UseFamiliesResult {
+  const hasInitial = Array.isArray(initialFamilies);
+  const initialRef = useRef<MineralFamily[] | undefined>(initialFamilies);
+  const [families, setFamilies] = useState<MineralFamily[]>(initialFamilies ?? []);
+  const [loading, setLoading] = useState(!hasInitial);
   const [error, setError] = useState<Error | null>(null);
 
   const loadAll = useCallback(async () => {
+    // Reset to SSG-fetched data without touching wasm DB when available.
+    if (initialRef.current) {
+      setFamilies(initialRef.current);
+      setLoading(false);
+      setError(null);
+      return;
+    }
     try {
       setLoading(true);
       setError(null);
@@ -115,8 +128,9 @@ export function useFamilies(): UseFamiliesResult {
   }, [loadAll]);
 
   useEffect(() => {
+    if (hasInitial) return;
     loadAll();
-  }, [loadAll]);
+  }, [loadAll, hasInitial]);
 
   return {
     families,
diff --git a/src/lib/db-server.ts b/src/lib/db-server.ts
index d4b60f8..184a831 100644
--- a/src/lib/db-server.ts
+++ b/src/lib/db-server.ts
@@ -298,6 +298,21 @@ export async function getCategories(): Promise<string[]> {
   return result[0].values.map((row) => row[0] as string);
 }
 
+/**
+ * Get distinct origin classifications from the families table.
+ */
+export async function getOrigins(): Promise<string[]> {
+  const database = await getDB();
+  const result = database.exec(
+    `SELECT DISTINCT origin FROM mineral_families
+     WHERE origin IS NOT NULL AND origin != ''
+     ORDER BY origin`
+  );
+
+  if (result.length === 0) return [];
+  return result[0].values.map((row) => row[0] as string);
+}
+
 /**
  * Get distinct mineral groups from the database.
  */
diff --git a/src/lib/sanitize-svg.ts b/src/lib/sanitize-svg.ts
index 2cf1ce9..f89b7fe 100644
--- a/src/lib/sanitize-svg.ts
+++ b/src/lib/sanitize-svg.ts
@@ -111,6 +111,14 @@ const SVG_CONFIG: DOMPurify.Config = {
 export function sanitizeSvg(svgContent: string): string {
   if (!svgContent) return '';
 
+  // SSR / Node has no window — DOMPurify cannot run without jsdom.
+  // The SVGs we render in SSG come from our own minerals.db (built by
+  // crystal-renderer), so we can pass them through unchanged on the server
+  // and let the browser-side hydration re-sanitise once the DOM is available.
+  if (typeof window === 'undefined') {
+    return svgContent;
+  }
+
   // DOMPurify.sanitize returns a string when not using RETURN_DOM options
   return DOMPurify.sanitize(svgContent, SVG_CONFIG) as string;
 }
diff --git a/src/pages/gallery/index.astro b/src/pages/gallery/index.astro
index baa8096..46290b1 100644
--- a/src/pages/gallery/index.astro
+++ b/src/pages/gallery/index.astro
@@ -3,6 +3,12 @@ import BaseLayout from '../../layouts/BaseLayout.astro';
 import { Gallery } from '../../components/gallery/Gallery';
 import { Container, SectionHeader } from '../../components/ui';
 import { getSiteStats } from '../../lib/stats';
+import {
+  getAllFamilies,
+  getCrystalSystems,
+  getOrigins,
+  getMineralGroups,
+} from '../../lib/db-server';
 
 const url = Astro.url;
 const initialSystem = url.searchParams.get('system') || '';
@@ -13,6 +19,16 @@ const initialOrigin = url.searchParams.get('origin') || '';
 const canonicalURL = 'https://gemmology.dev/gallery';
 
 const { familyCount } = await getSiteStats();
+
+// SSG-fetch families + filter dropdowns at build time so the gallery first
+// paint does not block on sql.js + the 8 MB minerals.db. The wasm DB only
+// loads client-side once the user actually searches or filters.
+const [initialFamilies, initialSystems, initialOrigins, initialGroups] = await Promise.all([
+  getAllFamilies(),
+  getCrystalSystems(),
+  getOrigins(),
+  getMineralGroups(),
+]);
 ---
 
 <BaseLayout
@@ -31,6 +47,10 @@ const { familyCount } = await getSiteStats();
         initialSystem={initialSystem}
         initialSearch={initialSearch}
         initialOrigin={initialOrigin}
+        initialFamilies={initialFamilies}
+        initialSystems={initialSystems}
+        initialOrigins={initialOrigins}
+        initialGroups={initialGroups}
       />
     </Container>
   </div>

From c5d274004cded92bc288da65e40155300f81fe21 Mon Sep 17 00:00:00 2001
From: Bissbert <43237892+Bissbert@users.noreply.github.com>
Date: Tue, 5 May 2026 18:02:26 +0700
Subject: [PATCH 3/3] feat(ux): playground retry, hero mobile spacing, 404
 polish
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- CDLPreview surfaces a Retry button in its error state; Playground
  passes generatePreview as the handler so transient render-API
  failures recover with one click.
- Hero CDL badge no longer overflows narrow viewports — pinned closer
  to the panel on small screens, padding scales up on sm+, and the
  code label truncates with ellipsis instead of bursting out of the
  card.
- 404 page replaces the muted "404" with a crystal lattice SVG and a
  more thematic "Lost in the lattice" heading, fixes the H3-before-H1
  hierarchy, and adds a third CTA (Learn) for users who landed on a
  bad article URL.
---
 src/components/playground/CDLPreview.tsx | 18 ++++++++++++++++--
 src/components/playground/Playground.tsx |  1 +
 src/pages/404.astro                      | 23 +++++++++++++++++------
 src/pages/index.astro                    |  6 +++---
 4 files changed, 37 insertions(+), 11 deletions(-)

diff --git a/src/components/playground/CDLPreview.tsx b/src/components/playground/CDLPreview.tsx
index 0e07dc3..ff29868 100644
--- a/src/components/playground/CDLPreview.tsx
+++ b/src/components/playground/CDLPreview.tsx
@@ -17,9 +17,11 @@ interface CDLPreviewProps {
   loading?: boolean;
   error?: string | null;
   className?: string;
+  /** Re-run the render request — surfaced as a Retry button in the error state. */
+  onRetry?: () => void;
 }
 
-export function CDLPreview({ svgContent, loading, error, className }: CDLPreviewProps) {
+export function CDLPreview({ svgContent, loading, error, className, onRetry }: CDLPreviewProps) {
   return (
     <div
       className={clsx(
@@ -55,7 +57,19 @@ export function CDLPreview({ svgContent, loading, error, className }: CDLPreview
                 d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"
               />
             </svg>
-            <p className="mt-2 text-sm text-red-600">{error}</p>
+            <p className="mt-2 text-sm text-red-700">{error}</p>
+            {onRetry && (
+              <button
+                type="button"
+                onClick={onRetry}
+                className="mt-4 inline-flex items-center gap-2 rounded-lg border border-red-300 bg-white px-3 py-1.5 text-sm font-medium text-red-700 hover:bg-red-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-red-600"
+              >
+                <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15" />
+                </svg>
+                Retry
+              </button>
+            )}
           </div>
         </div>
       )}
diff --git a/src/components/playground/Playground.tsx b/src/components/playground/Playground.tsx
index dd0a008..fa972c5 100644
--- a/src/components/playground/Playground.tsx
+++ b/src/components/playground/Playground.tsx
@@ -269,6 +269,7 @@ export function Playground({ initialCDL }: PlaygroundProps) {
                 loading={previewLoading}
                 error={previewError}
                 className="h-full"
+                onRetry={() => generatePreview(cdlCode)}
               />
             ) : (
               <div className="h-full relative">
diff --git a/src/pages/404.astro b/src/pages/404.astro
index ad7fb74..26010d2 100644
--- a/src/pages/404.astro
+++ b/src/pages/404.astro
@@ -19,23 +19,34 @@ const popularPages = [
 
 <BaseLayout title="Page Not Found" description="The page you're looking for doesn't exist.">
   <Container size="md" padding="lg" class="min-h-[60vh] flex flex-col items-center justify-center text-center">
-    <h1 class="text-6xl font-bold text-slate-300 mb-4">404</h1>
-    <h2 class="text-2xl font-semibold text-slate-900 mb-4">Page Not Found</h2>
+    <div class="relative mb-8" aria-hidden="true">
+      <svg class="w-32 h-32 text-crystal-200" viewBox="0 0 200 200" fill="none" stroke="currentColor" stroke-width="1.5">
+        <polygon points="100,30 160,80 130,160 70,160 40,80" fill="currentColor" fill-opacity="0.18"/>
+        <polygon points="100,30 160,80 130,160 70,160 40,80"/>
+        <line x1="100" y1="30" x2="100" y2="160" stroke-opacity="0.4"/>
+        <line x1="40" y1="80" x2="160" y2="80" stroke-opacity="0.4"/>
+        <line x1="70" y1="160" x2="160" y2="80" stroke-opacity="0.3"/>
+        <line x1="130" y1="160" x2="40" y2="80" stroke-opacity="0.3"/>
+      </svg>
+      <span class="absolute inset-0 flex items-center justify-center text-4xl font-bold text-slate-700">404</span>
+    </div>
+    <h1 class="text-3xl sm:text-4xl font-semibold text-slate-900 mb-3">Lost in the lattice</h1>
     <p class="text-slate-600 mb-8 max-w-md">
-      The page you're looking for doesn't exist or has been moved.
+      The page you're looking for doesn't exist or has been moved. Try one of the routes below or head back to the gallery.
     </p>
 
-    <div class="flex gap-4 mb-12">
+    <div class="flex flex-wrap justify-center gap-4 mb-12">
       <Button href="/" variant="primary">Go Home</Button>
       <Button href="/gallery" variant="secondary">Browse Gallery</Button>
+      <Button href="/learn" variant="ghost">Open Learn</Button>
     </div>
 
     <div class="w-full max-w-2xl">
-      <h3 class="text-lg font-semibold text-slate-900 mb-4">Popular Pages</h3>
+      <h2 class="text-lg font-semibold text-slate-900 mb-4">Popular Pages</h2>
       <div class="grid grid-cols-1 sm:grid-cols-2 gap-4">
         {popularPages.map(page => (
           <Card href={page.href} hover padding="md">
-            <h4 class="font-medium text-slate-900">{page.title}</h4>
+            <h3 class="font-medium text-slate-900">{page.title}</h3>
             <p class="text-sm text-slate-600 mt-1">{page.description}</p>
           </Card>
         ))}
diff --git a/src/pages/index.astro b/src/pages/index.astro
index a738d16..5cb4ace 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -135,15 +135,15 @@ const iconPaths: Record<string, string> = {
         </div>
 
         <!-- Hero Crystal SVG -->
-        <div class="relative">
+        <div class="relative mt-8 lg:mt-0">
           <div class="aspect-square max-w-md mx-auto">
             <div class="absolute inset-0 rounded-2xl bg-gradient-to-br from-crystal-100/50 to-slate-100/50 -rotate-6"></div>
             <div class="relative rounded-2xl border border-slate-200/50 bg-white/80 backdrop-blur-sm shadow-xl overflow-hidden" style="aspect-ratio: 1;">
               <HeroCrystal3D client:load mineralName="Diamond" rotationSpeed={0.3} className="w-full h-full" />
             </div>
           </div>
-          <div class="absolute -bottom-4 -right-4 bg-white rounded-lg shadow-lg border border-slate-200 px-4 py-2">
-            <code class="text-sm font-mono text-slate-700">cubic[m3m]:{'{'}{'{'}111{'}'}</code>
+          <div class="absolute right-2 -bottom-3 sm:-right-2 sm:-bottom-4 bg-white rounded-lg shadow-lg border border-slate-200 px-3 py-1.5 sm:px-4 sm:py-2 max-w-[calc(100%-1rem)]">
+            <code class="text-xs sm:text-sm font-mono text-slate-700 whitespace-nowrap overflow-hidden text-ellipsis block">cubic[m3m]:{'{'}{'{'}111{'}'}</code>
           </div>
         </div>
       </div>