## Stack
- Astro: 5.x (NOT 4.x — content layer API, server islands, and routing differ)
- Output: static (NOT server/hybrid — no SSR unless explicitly noted)
- UI framework for islands: React 18 (used ONLY for interactive components)
- Styling: Tailwind CSS 4.x
- Node: 22 LTS

## Astro Component Model
The frontmatter section of .astro files (between ---) runs on the SERVER only.
NEVER use browser APIs (window, document, localStorage, fetch with credentials)
in .astro frontmatter.

// CORRECT — server-side in frontmatter
---
const posts = await getCollection('blog');
const data = await fetch('https://api.example.com/data').then(r => r.json());
---

// WRONG — browser API in frontmatter (throws at build time)
---
const saved = localStorage.getItem('theme'); // window is undefined on server
---

## Islands Architecture
Interactive components MUST declare a hydration directive explicitly.
Do NOT add client:load to every component — this defeats Astro's performance model.

Choose the right directive:
- client:load   → hydrate immediately (use for above-the-fold critical UI only)
- client:idle   → hydrate when browser is idle (most interactive components)
- client:visible → hydrate when component enters viewport (below-fold content)
- client:only   → skip SSR entirely (use only when component CANNOT run on server)

// CORRECT
<SearchBar client:idle />
<NewsletterForm client:visible />
<VideoPlayer client:only="react" />

// WRONG — hydrating everything immediately
<Header client:load />
<Footer client:load />
<Sidebar client:load />

## Content Management
ALL blog posts, documentation, case studies, and structured content MUST use
Astro Content Collections defined in src/content/config.ts.
Never import markdown files with raw import statements.
Never store content as hardcoded arrays in .astro files.

// CORRECT — src/content/config.ts
import { defineCollection, z } from 'astro:content';
export const collections = {
  blog: defineCollection({
    type: 'content',
    schema: z.object({
      title: z.string(),
      pubDate: z.date(),
      tags: z.array(z.string()),
    }),
  }),
};

// In page
const posts = await getCollection('blog');

// WRONG
import post from '../content/post.md'; // raw import bypasses collection

## Images
ALL images MUST use Astro's built-in <Image> or <Picture> component.
Never use raw <img> tags for content images.
Images in src/assets/ are optimized at build time.
External images require explicit width and height props.

// CORRECT
import { Image } from 'astro:assets';
import heroImage from '../assets/hero.jpg';

<Image src={heroImage} alt="Hero" />
<Image src="https://example.com/img.jpg" alt="External" width={800} height={600} />

// WRONG
<img src="/images/hero.jpg" alt="Hero" />  // no optimization

## CSS Scoping
Styles in <style> blocks inside .astro files are SCOPED to that component by default.
To apply global styles, use <style is:global> or import from a CSS file.
NEVER use :global() selector for component-specific styles — it leaks into the page.

// CORRECT — scoped (default)
<style>
  .card { border-radius: 8px; }  // only applies to this component's .card
</style>

// CORRECT — intentionally global
<style is:global>
  :root { --color-primary: #3b82f6; }
</style>

// WRONG — global override for a local component concern
<style>
  :global(.card) { border-radius: 8px; }  // leaks everywhere
</style>

## API Routes
Server-side API endpoints go in src/pages/api/ as .ts files.
They export a named function for each HTTP method.
API routes only work in SSR mode (output: 'server' or 'hybrid').
In static output mode, API routes are NOT available — use edge functions or external APIs.

// CORRECT — src/pages/api/subscribe.ts (SSR mode only)
import type { APIRoute } from 'astro';

export const POST: APIRoute = async ({ request }) => {
  const body = await request.json();
  // process...
  return new Response(JSON.stringify({ success: true }), {
    headers: { 'Content-Type': 'application/json' },
  });
};

## Environment Variables
Server-only secrets: use import.meta.env.SECRET_KEY (never exposed to client)
Client-safe variables: must be prefixed PUBLIC_ (e.g., PUBLIC_SITE_URL)
NEVER use process.env in Astro — it doesn't work in all environments.

// CORRECT
const apiKey = import.meta.env.SECRET_API_KEY;     // server only
const siteUrl = import.meta.env.PUBLIC_SITE_URL;   // safe for client

// WRONG
const apiKey = process.env.SECRET_API_KEY;          // may be undefined in Astro

## Dynamic Routes
Static output pages with URL parameters MUST export getStaticPaths() to define
all valid paths at build time.
In SSR mode, getStaticPaths is not required (routes are resolved at runtime).

// CORRECT — static output dynamic route
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

## Layout Convention
The <html>, <head>, and <body> tags belong in layout files (src/layouts/).
Page .astro files use a layout component for document structure.
Component .astro files NEVER render <html>, <head>, or <body>.

// CORRECT — src/layouts/BaseLayout.astro
---
const { title } = Astro.props;
---
<!DOCTYPE html>
<html lang="en">
  <head><title>{title}</title></head>
  <body><slot /></body>
</html>

// Page uses layout
---
import BaseLayout from '../layouts/BaseLayout.astro';
---
<BaseLayout title="Home">
  <h1>Welcome</h1>
</BaseLayout>

## TypeScript
This project uses TypeScript strict mode (tsconfig: astro/tsconfigs/strict).
No implicit any. No type assertions without justification.
Astro component props MUST be typed with Props interface.

// CORRECT
interface Props {
  title: string;
  description?: string;
  pubDate: Date;
}
const { title, description, pubDate } = Astro.props;

// WRONG
const { title, description, pubDate } = Astro.props; // untyped in strict mode

## Component Choice
Use .astro components for all static or server-rendered UI.
Use React/Vue/Svelte components ONLY when the component needs client-side
interactivity (state, event handlers, browser APIs).
A component that only displays data and has no event handlers should be .astro.

// CORRECT — static card with no interactivity → .astro component
// CORRECT — search with onChange handler → React component with client:idle
// WRONG — React component with no state/events → use .astro instead

## Build and Preview
Use these commands for development and verification:
- npm run dev       → development server (localhost:4321)
- npm run build     → production build (output to dist/)
- npm run preview   → preview production build locally

For checking bundle size: npx astro build && ls -la dist/

TypeScript check without building: npx astro check