Troubleshooting

// BEFORE (FR-1 violation — client-rendered)
'use client';
export default function Products() {
  const [products, setProducts] = useState([]);
  useEffect(() => {
    fetch('/api/products').then(r => r.json()).then(setProducts);
  }, []);
  return <ul>{products.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
}

// AFTER (FR-1 compliant — server-rendered)
export default async function Products() {
  const products = await fetch('/api/products').then(r => r.json());
  return <ul>{products.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
}

// Check: does your page component fetch on client or server?
// In Next.js App Router, any async function = server component
export default async function Page({ params }) {
  // This runs on the server — data is in initial HTML
  const data = await getData(params.id);
  return <div data-agent-page="product">{data.name}</div>;
}

<!-- WRONG: two h1s -->
<h1>Site Name</h1>  <!-- in header -->
<h1>Product Name</h1>  <!-- in content -->

<!-- RIGHT: one h1 -->
<header>
  <a href="/">Site Name</a>  <!-- not a heading -->
</header>
<main>
  <h1 data-agent-content="page-title">Product Name</h1>
</main>

// Suspense with server-rendered fallback
import { Suspense } from 'react';

export default function Page() {
  return (
    <main data-agent-page="product-listing" data-agent-intent="browse">
      <Suspense
        fallback={
          <div
            data-agent-component="product-list"
            data-agent-mitigation="skeleton"
          >
            Loading products...
          </div>
        }
      >
        <ProductList />
      </Suspense>
    </main>
  );
}

// Next.js App Router — JSON-LD in server component
export default async function ProductPage({ params }) {
  const product = await getProduct(params.id);

  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'Product',
    name: product.name,
    offers: {
      '@type': 'Offer',
      price: product.price,
      priceCurrency: 'USD',
    },
  };

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
      />
      <main data-agent-page="product-detail">
        {/* ... */}
      </main>
    </>
  );
}

// app/api/openapi.json/route.ts
import { NextResponse } from 'next/server';
import spec from '@/lib/openapi-spec.json';

export async function GET() {
  return NextResponse.json(spec, {
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Cache-Control': 'public, max-age=3600',
    },
  });
}

// app/api/products/route.ts
export async function GET(req: Request) {
  const products = await getProducts();

  return new Response(JSON.stringify(products), {
    headers: {
      'Content-Type': 'application/json',
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  });
}

export async function OPTIONS() {
  return new Response(null, {
    status: 200,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  });
}

// Option 1: static file
// Place at: public/.well-known/agent.json
// Served at: /.well-known/agent.json

// Option 2: route handler
// app/.well-known/agent.json/route.ts
export async function GET() {
  return Response.json({
    schemaVersion: '1.0',
    name: 'YourSite Agent',
    // ...
  });
}