Hybrid Frontend — full notes, searchable

Contains every small box below (how-to, 99-line agent, rules, golden, stack, never-do, tips, prompts, checklist, fluid CSS, no-React-state). One click copies the full hybrid for an AI agent.

• Live build of a content site → paste the 99-line box into the agent first.
• Pick a stack from §4 before writing code. Do not default to React for docs.
• Then open the matching prompt in §7 (scaffold / virtualize / Pagefind / audit).
• This organizer itself follows the below-part: CSS :checked-free details, clamp, dvh, no React state.

Title: Hybrid Frontend Architecture Agent — Static-First SSG, Islands Hydration, Virtualized Lists, Prefetch, Event Delegation, Pagefind, CDN

Function role

1. Operating manual for huge-content sites that must stay fast, stable, and low-RAM: SSG many small pages, not one giant HTML.
2. Eight hybrid rules plus five golden rules: one topic/page, zero-JS default, virtualize/paginate, lazy, prefetch, one parent listener, content in MD/JSON, Brotli+CDN.
3. Stack picker (Astro/Pagefind vs SvelteKit+TanStack vs plain HTML vs SSR+Meilisearch) and a never-do list.
4. Copy-paste AI prompts for scaffold, virtual list, Pagefind, audit, monolith migration, hover-prefetch, delegation.
5. Below-the-box organizer: search, two themes, expandable sections, fluid clamp/dvh CSS, CSS-first UI with almost no React state.

Situation	Stack	Why
Docs, wiki, blog, KB	Astro + Markdown + Pagefind + CDN	Zero-JS default, SEO, fastest loads
Dashboards, logs, huge tables	SvelteKit / SolidStart + TanStack Virtual + API	Light reactivity, virtualization
No-build, ultra simple	Plain HTML + vanilla JS + pagination	Zero deps, trivial host
User-generated, dynamic	Next.js / Nuxt SSR + Meilisearch + CDN	Freshness + search
SPA feel without SPA weight	Astro + htmx/Alpine + prefetch	Still multi-page under the hood

SSG: Astro zero JS · 11ty simple · Hugo fastest Go. Content stays in MD/JSON.

Do not	Do instead
One HTML with 50,000 lines	Split pages; SSG
All topics on the homepage	Paginate or topic index
100,000 table rows in the DOM	Virtualize or server paginate
Ship React for a static blog	Astro or plain HTML
Click listener on every item	One parent listener
Search index on every load	Lazy load when search opens
Ignore cache headers	Immutable assets, revalidate HTML

Content

• Markdown/MDX — portable, versioned, writing ≠ code.
• Folders /content/category/topic.md auto-build indexes.
• Generate topic pages at build time, never runtime.

Speed

• Hover prefetch (5-line script or Astro prefetch).
• One small CSS file beats over-preloading.
• Native View Transitions API — no framework.

Lists / search / deploy

• <500 paginate · 500–10k clusterize.js or content-visibility · 10k+ TanStack Virtual.
• <1k pages: Pagefind / Fuse.js. 10k+: Meilisearch / Typesense.
• Assets: public, max-age=31536000, immutable. HTML: max-age=0, must-revalidate.
• Images: WebP/AVIF, width+height, lazy+async. Fonts: self-host, font-display:swap.
• Web Worker for 100k-row JSON filter. defer scripts. Minify.

document.getElementById("list").addEventListener("click", (e) => {
  const item = e.target.closest("[data-id]");
  if (item) handleClick(item.dataset.id);
});

A · Scaffold. Astro, Markdown in /content/, one page per topic at /topics/[slug]/index.html, min CSS, zero client JS except search, hover prefetch, static host.

B · Virtual list. TanStack Virtual or vanilla. 50,000+ rows. Delegation. 60fps. Under 50MB RAM.

C · Pagefind. Do not load the index on first paint. Init on search focus. No external API.

D · Audit. JS size, DOM count, unused CSS, lazy images, cache headers, Brotli, listener count. Fix over-threshold items.

E · Migrate 30k-line HTML. URL per topic, extract CSS/JS, Astro or 11ty, paginate/virtualize, CDN.

Hover prefetch. Vanilla: hover on internal a injects link[rel=prefetch], skip duplicates.

Delegation. #topic-list parent, hundreds of child buttons, one listener.

Instant nav. Fetch HTML, swap main, pushState, prefetch on hover, degrade if JS is off.

• CDN serving Brotli (or gzip) for HTML/CSS/JS/SVG.
• WebP/AVIF + width/height + loading="lazy".
• Self-hosted fonts, font-display: swap, preload only above-fold weights.
• Hashed assets immutable one year. HTML revalidate.
• Heavy parse → Web Worker. Progressive enhancement: readable with JS off.
• Service worker only if offline is a real requirement.

Final recipe: Astro + Markdown/MDX + static HTML + Pagefind + tiny CSS + minimal JS + pagination/virtualization + lazy + prefetch + cache + CDN.

• clamp(min, preferred, max) for font, padding, gap. Example font-size: clamp(1rem, 2.5vw, 1.5rem).
• Pair with min() / max(). Container max: min(100%, 600px).
• Images: aspect-ratio: 16/9; object-fit: cover; max-width: 100%; height: auto;
• Viewport: dvh / svh / lvh — not raw vh (mobile chrome).
• Container queries when supported — style the component, not the viewport.
• Logical props: margin-inline, padding-block, width: fit-content, grid auto-fit + minmax().

• Hover, checkbox + :checked / :has(), details, CSS transitions for open/close — not useState.
• useRef for focus, measure, DOM, timers (no re-render).
• Composition over state. Uncontrolled children. Do not lift state high.
• Skip state for modals/tooltips/animations CSS can do.
• If state is required: keep it local. useMemo/useCallback only after profiling.
• External store only for truly global data. Result: fewer re-renders, snappier low-end pages.