@masters-ws/react-seo 1.4.4 → 1.5.1

package/README.md

@@ -1,1482 +1,308 @@
-[![Total Downloads](https://img.shields.io/npm/dt/@masters-ws/react-seo.svg?style=flat-square)](https://www.npmjs.com/package/@masters-ws/react-seo)
-# @masters-ws/react-seo
-
-Professional high-performance SEO package for React and Next.js. **Zero-dependency core** for Next.js App Router + optional Helmet components for universal React support.
-
-## Key Features
-
-- ✅ **Zero-Dependency Core** — Pure functions for Next.js (no react-helmet-async needed!)
-- ✅ **SSR-First Architecture** — All metadata rendered server-side for Google crawlers
-- ✅ **Clean JSON-LD** — Automatic removal of `undefined`/`null` values from schemas
-- ✅ **@graph Support** — Combine multiple schemas into a single `<script>` tag (Google recommended)
-- ✅ **Full Metadata Support** — Title, Description, OG, Twitter Cards, Canonical, Robots
-- ✅ **Intelligent Pagination** — Automatic `rel="prev"` and `rel="next"` handling
-- ✅ **30+ Schema Types** — Product, Article, FAQ, Event, LocalBusiness, Video, Recipe, etc.
-- ✅ **Rich Product Schema** — Multi-image, reviews, return policy, shipping, variants
-- ✅ **Convenience Helpers** — One-call setup: Product, Article, Category pages
-- ✅ **Development Warnings** — Console warnings for missing required schema fields
-- ✅ **i18n Ready** — No hardcoded strings, all labels are configurable
-- ✅ **Multilingual Support** — Easy `hreflang` management
-- ✅ **Performance Optimized** — DNS Prefetch, Preconnect, Preload support
-
-## Installation
-
-### For Next.js App Router (Zero Dependencies):
-```bash
-npm install @masters-ws/react-seo
-```
-
-### For React / Next.js Pages Router (With Components):
-```bash
-npm install @masters-ws/react-seo react-helmet-async
-```
-
----
-
-## 🚀 Quick Start: Next.js App Router (Recommended)
-
-### Product Page (One-Call Setup)
-
-```tsx
-// app/products/[slug]/page.tsx — Server Component (NO 'use client')
-import { generateProductMetadata, JsonLd } from '@masters-ws/react-seo/core';
-
-const siteConfig = {
-  name: "My Store",
-  url: "https://store.com",
-  logo: "https://store.com/logo.png",
-  description: "Best online store",
-  language: "en_US",
-};
-
-// ✅ Server-side metadata — Google sees it immediately!
-export async function generateMetadata({ params }: { params: { slug: string } }) {
-  const product = await fetchProduct(params.slug);
-  const { metadata } = generateProductMetadata({
-    name: product.name,
-    description: product.short_description,
-    image: [product.main_image, ...product.gallery],  // Multi-image support
-    price: product.price,
-    currency: "USD",
-    sku: product.sku,
-    brand: product.brand?.name,
-    availability: product.in_stock
-      ? "https://schema.org/InStock"
-      : "https://schema.org/OutOfStock",
-    url: `https://store.com/products/${params.slug}`,
-    metaTitle: product.meta_title,
-    metaDescription: product.meta_description,
-
-    // Individual reviews (optional)
-    reviews: product.reviews?.map(r => ({
-      author: r.user.name,
-      ratingValue: r.rating,
-      reviewBody: r.comment,
-      datePublished: r.created_at,
-    })),
-
-    // Return policy (optional)
-    returnPolicy: {
-      returnPolicyCategory: 'MerchantReturnFiniteReturnWindow',
-      returnWithin: 30,
-      returnMethod: 'ReturnByMail',
-      returnFees: 'FreeReturn',
-    },
-
-    // Shipping (optional)
-    shipping: {
-      shippingRate: { value: 5.99, currency: "USD" },
-      shippingDestination: "US",
-      deliveryTime: { minDays: 3, maxDays: 7 },
-    },
-
-    // Product variants (optional — generates AggregateOffer)
-    variants: product.variants?.map(v => ({
-      name: v.name,
-      sku: v.sku,
-      price: v.price,
-    })),
-
-    breadcrumbs: [
-      { name: "Home", item: "https://store.com" },
-      { name: "Shop", item: "https://store.com/shop" },
-      { name: product.category?.name, item: `https://store.com/categories/${product.category?.slug}` },
-      { name: product.name, item: `https://store.com/products/${params.slug}` },
-    ],
-  }, siteConfig);
-
-  return metadata;
-}
-
-// ✅ Server-rendered JSON-LD schemas with @graph pattern
-export default async function ProductPage({ params }: { params: { slug: string } }) {
-  const product = await fetchProduct(params.slug);
-  const { schemas } = generateProductMetadata({ /* same data */ }, siteConfig);
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <ProductDetailClient product={product} />
-    </>
-  );
-}
-```
-
-**What Google sees in the HTML source:**
-```html
-<!-- ✅ Server-rendered <head> tags -->
-<title>Product Name | My Store</title>
-<meta name="description" content="Product description..." />
-<meta property="og:title" content="Product Name" />
-<meta property="og:image" content="https://store.com/product.jpg" />
-<meta property="og:type" content="product" />
-<meta name="twitter:card" content="summary_large_image" />
-<link rel="canonical" href="https://store.com/products/my-product" />
-
-<!-- ✅ Server-rendered JSON-LD with @graph -->
-<script type="application/ld+json">
-{
-  "@context": "https://schema.org",
-  "@graph": [
-    { "@type": "Product", "name": "...", "offers": {...}, "review": [...] },
-    { "@type": "BreadcrumbList", "itemListElement": [...] },
-    { "@type": "Organization", "name": "...", "logo": "..." },
-    { "@type": "WebSite", "name": "...", "potentialAction": {...} }
-  ]
-}
-</script>
-```
-
-### Article Page (One-Call Setup)
-
-```tsx
-// app/news/[slug]/page.tsx — Server Component
-import { generateArticleMetadata, JsonLd } from '@masters-ws/react-seo/core';
-
-export async function generateMetadata({ params }) {
-  const article = await fetchArticle(params.slug);
-  const { metadata } = generateArticleMetadata({
-    title: article.title,
-    description: article.excerpt,
-    image: article.cover_image,
-    publishedTime: article.published_at,
-    modifiedTime: article.updated_at,
-    author: { name: article.author.name, url: article.author.url },
-    url: `https://mysite.com/news/${params.slug}`,
-    category: article.category,
-    tags: article.tags,
-    readingTime: article.reading_time,
-    wordCount: article.word_count,
-  }, siteConfig);
-
-  return metadata;
-}
-
-export default async function ArticlePage({ params }) {
-  const article = await fetchArticle(params.slug);
-  const { schemas } = generateArticleMetadata({ /* same data */ }, siteConfig);
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <article>...</article>
-    </>
-  );
-}
-```
-
-### Category Page with Pagination
-
-```tsx
-// app/categories/[slug]/page.tsx — Server Component
-import { generateCategoryMetadata, JsonLd } from '@masters-ws/react-seo/core';
-
-export async function generateMetadata({ params, searchParams }) {
-  const page = Number(searchParams.page) || 1;
-  const category = await fetchCategory(params.slug);
-  const { metadata } = generateCategoryMetadata({
-    name: category.name,
-    description: category.description,
-    url: `https://store.com/categories/${params.slug}`,
-    image: category.image,
-    page,
-    totalPages: category.totalPages,
-    // Products on this page → generates ItemList schema
-    items: category.products.map((p, i) => ({
-      name: p.name,
-      url: `https://store.com/products/${p.slug}`,
-      image: p.image,
-      position: i + 1,
-    })),
-  }, siteConfig);
-
-  return metadata;
-}
-
-export default async function CategoryPage({ params, searchParams }) {
-  const page = Number(searchParams.page) || 1;
-  const category = await fetchCategory(params.slug);
-  const { schemas } = generateCategoryMetadata({ /* same data */ }, siteConfig);
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <ProductGrid products={category.products} />
-    </>
-  );
-}
-```
-
----
-
-## 📰 Use Case: Blog / News Site
-
-A complete guide for setting up SEO on a blog or news website.
-
-### Blog Homepage
-
-```tsx
-// app/page.tsx — Server Component
-import { generateHomepageMetadata, JsonLd } from '@masters-ws/react-seo/core';
-
-const siteConfig = {
-  name: "Tech Blog",
-  url: "https://techblog.com",
-  logo: "https://techblog.com/logo.png",
-  description: "Latest technology news, tutorials, and insights",
-  language: "en_US",
-  twitterHandle: "@techblog",
-  socialLinks: [
-    "https://twitter.com/techblog",
-    "https://facebook.com/techblog",
-    "https://linkedin.com/company/techblog",
-  ],
-};
-
-export async function generateMetadata() {
-  const { metadata } = generateHomepageMetadata({
-    title: "Tech Blog — Latest Technology News & Tutorials",
-    description: "Stay updated with the latest tech news, programming tutorials, and expert insights.",
-    ogImage: "https://techblog.com/og-cover.jpg",
-  }, siteConfig);
-
-  return metadata;
-}
-
-export default function HomePage() {
-  const { schemas } = generateHomepageMetadata({
-    title: "Tech Blog — Latest Technology News & Tutorials",
-    description: "Stay updated with the latest tech news, programming tutorials, and expert insights.",
-  }, siteConfig);
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <main>
-        <h1>Welcome to Tech Blog</h1>
-        {/* Latest articles grid */}
-      </main>
-    </>
-  );
-}
-```
-
-### Article / Blog Post Page
-
-```tsx
-// app/blog/[slug]/page.tsx — Server Component
-import { generateArticleMetadata, JsonLd } from '@masters-ws/react-seo/core';
-
-export async function generateMetadata({ params }: { params: { slug: string } }) {
-  const article = await fetchArticle(params.slug);
-
-  const { metadata } = generateArticleMetadata({
-    title: article.title,
-    description: article.excerpt,
-    image: article.cover_image,
-    publishedTime: article.published_at,       // ISO 8601
-    modifiedTime: article.updated_at,
-    author: {
-      name: article.author.name,
-      url: `https://techblog.com/authors/${article.author.slug}`,
-    },
-    url: `https://techblog.com/blog/${params.slug}`,
-    category: article.category.name,           // e.g. "JavaScript"
-    tags: article.tags.map(t => t.name),       // ["React", "Next.js", "SEO"]
-    readingTime: article.reading_time,         // e.g. 5 (minutes)
-    wordCount: article.word_count,
-
-    breadcrumbs: [
-      { name: "Home", item: "https://techblog.com" },
-      { name: article.category.name, item: `https://techblog.com/category/${article.category.slug}` },
-      { name: article.title, item: `https://techblog.com/blog/${params.slug}` },
-    ],
-  }, siteConfig);
-
-  return metadata;
-}
-
-export default async function ArticlePage({ params }: { params: { slug: string } }) {
-  const article = await fetchArticle(params.slug);
-  const { schemas } = generateArticleMetadata({ /* same data as above */ }, siteConfig);
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <article>
-        <h1>{article.title}</h1>
-        <p>By {article.author.name} · {article.reading_time} min read</p>
-        <div dangerouslySetInnerHTML={{ __html: article.content }} />
-      </article>
-    </>
-  );
-}
-```
-
-**What Google sees:**
-```html
-<title>How to Master SEO in Next.js | Tech Blog</title>
-<meta name="description" content="A comprehensive guide to..." />
-<meta property="og:type" content="article" />
-<meta property="article:published_time" content="2024-06-15T10:00:00Z" />
-<meta property="article:author" content="John Doe" />
-<meta property="article:section" content="JavaScript" />
-<meta property="article:tag" content="React,Next.js,SEO" />
-<script type="application/ld+json">
-{
-  "@context": "https://schema.org",
-  "@graph": [
-    { "@type": "NewsArticle", "headline": "...", "author": { "@type": "Person", "name": "..." } },
-    { "@type": "BreadcrumbList", "itemListElement": [...] },
-    { "@type": "Organization", ... },
-    { "@type": "WebSite", "potentialAction": { "@type": "SearchAction", ... } }
-  ]
-}
-</script>
-```
-
-### Blog Category Page (with Pagination)
-
-```tsx
-// app/category/[slug]/page.tsx — Server Component
-import { generateCategoryMetadata, JsonLd } from '@masters-ws/react-seo/core';
-
-export async function generateMetadata({ params, searchParams }) {
-  const page = Number(searchParams.page) || 1;
-  const category = await fetchCategory(params.slug);
-
-  const { metadata } = generateCategoryMetadata({
-    name: category.name,
-    description: `All articles about ${category.name}`,
-    url: `https://techblog.com/category/${params.slug}`,
-    image: category.cover_image,
-    page,
-    totalPages: category.totalPages,
-    // Articles on this page → generates ItemList schema
-    items: category.articles.map((a, i) => ({
-      name: a.title,
-      url: `https://techblog.com/blog/${a.slug}`,
-      image: a.cover_image,
-      position: (page - 1) * 10 + i + 1,
-    })),
-  }, siteConfig);
-
-  return metadata;
-}
-
-export default async function CategoryPage({ params, searchParams }) {
-  const page = Number(searchParams.page) || 1;
-  const category = await fetchCategory(params.slug);
-  const { schemas } = generateCategoryMetadata({ /* same data */ }, siteConfig);
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <h1>{category.name}</h1>
-      <ArticleGrid articles={category.articles} />
-      <Pagination current={page} total={category.totalPages} />
-    </>
-  );
-}
-```
-
-> **Pagination SEO is automatic!** The helper generates:
-> - `rel="canonical"` (without `?page=1` for page 1)
-> - `rel="prev"` / `rel="next"` links
-> - Page number in title (e.g. "JavaScript - Page 2")
-
-### Author Page
-
-```tsx
-// app/authors/[slug]/page.tsx — Server Component
-import {
-  toNextMetadata,
-  generateWebPageSchema,
-  generateOrganizationSchema,
-  JsonLd
-} from '@masters-ws/react-seo/core';
-
-export async function generateMetadata({ params }) {
-  const author = await fetchAuthor(params.slug);
-
-  return toNextMetadata({
-    title: `${author.name} — Author at Tech Blog`,
-    description: author.bio,
-    image: author.avatar,
-    type: 'profile',
-    canonical: `https://techblog.com/authors/${params.slug}`,
-  }, siteConfig);
-}
-
-export default async function AuthorPage({ params }) {
-  const author = await fetchAuthor(params.slug);
-
-  const schemas = [
-    {
-      "@context": "https://schema.org",
-      "@type": "Person",
-      "name": author.name,
-      "description": author.bio,
-      "image": author.avatar,
-      "jobTitle": author.job_title,
-      "url": `https://techblog.com/authors/${params.slug}`,
-      "sameAs": author.social_links,
-    },
-    generateOrganizationSchema(siteConfig),
-  ];
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <h1>{author.name}</h1>
-      <p>{author.bio}</p>
-      <ArticleGrid articles={author.articles} />
-    </>
-  );
-}
-```
-
-### Tag Page
-
-```tsx
-// app/tag/[slug]/page.tsx — Server Component
-import { generateCategoryMetadata, JsonLd } from '@masters-ws/react-seo/core';
-
-export async function generateMetadata({ params, searchParams }) {
-  const page = Number(searchParams.page) || 1;
-  const tag = await fetchTag(params.slug);
-
-  // Reuse generateCategoryMetadata — tags are just another type of collection!
-  const { metadata } = generateCategoryMetadata({
-    name: `Tag: ${tag.name}`,
-    description: tag.description || `All articles tagged with "${tag.name}"`,
-    url: `https://techblog.com/tag/${params.slug}`,
-    page,
-    totalPages: tag.totalPages,
-    noindex: tag.totalPages <= 1, // noindex thin tag pages
-  }, siteConfig);
-
-  return metadata;
-}
-```
-
-### Article with FAQ Section
-
-```tsx
-// app/blog/[slug]/page.tsx — If the article has an FAQ section
-import { generateArticleMetadata, generateFAQSchema, JsonLd } from '@masters-ws/react-seo/core';
-
-export default async function ArticlePage({ params }) {
-  const article = await fetchArticle(params.slug);
-  const { schemas: articleSchemas } = generateArticleMetadata({ /* ... */ }, siteConfig);
-
-  // Add FAQ schema if article has FAQ section
-  const allSchemas = [...articleSchemas];
-  if (article.faqs?.length > 0) {
-    allSchemas.push(generateFAQSchema(
-      article.faqs.map(f => ({ q: f.question, a: f.answer }))
-    ));
-  }
-
-  return (
-    <>
-      <JsonLd schema={allSchemas} graph />
-      <article>
-        <h1>{article.title}</h1>
-        <div>{article.content}</div>
-        {article.faqs?.length > 0 && (
-          <section>
-            <h2>Frequently Asked Questions</h2>
-            {article.faqs.map(faq => (
-              <details key={faq.question}>
-                <summary>{faq.question}</summary>
-                <p>{faq.answer}</p>
-              </details>
-            ))}
-          </section>
-        )}
-      </article>
-    </>
-  );
-}
-```
-
----
-
-## 🏢 Use Case: Showcase / Branding Website
-
-A complete guide for corporate sites, portfolios, landing pages, and service-based businesses.
-
-### Homepage
-
-```tsx
-// app/page.tsx — Server Component
-import { generateHomepageMetadata, JsonLd } from '@masters-ws/react-seo/core';
-
-const siteConfig = {
-  name: "Acme Solutions",
-  url: "https://acme.com",
-  logo: "https://acme.com/logo.png",
-  description: "Digital solutions for modern businesses",
-  language: "en_US",
-  twitterHandle: "@acme",
-  socialLinks: [
-    "https://twitter.com/acme",
-    "https://linkedin.com/company/acme",
-    "https://github.com/acme",
-  ],
-};
-
-export async function generateMetadata() {
-  const { metadata } = generateHomepageMetadata({
-    title: "Acme Solutions — Digital Solutions for Modern Businesses",
-    description: "We help businesses grow with cutting-edge web development, mobile apps, and cloud solutions.",
-    ogImage: "https://acme.com/og-image.jpg",
-
-    // Add LocalBusiness if you have a physical office
-    localBusiness: {
-      name: "Acme Solutions HQ",
-      description: "Software development company",
-      telephone: "+1-555-123-4567",
-      address: {
-        street: "123 Tech Avenue",
-        city: "San Francisco",
-        region: "CA",
-        postalCode: "94105",
-        country: "US",
-      },
-      geo: { lat: 37.7749, lng: -122.4194 },
-      openingHours: ["Mo-Fr 09:00-18:00"],
-    },
-  }, siteConfig);
-
-  return metadata;
-}
-
-export default function HomePage() {
-  const { schemas } = generateHomepageMetadata({ /* same data */ }, siteConfig);
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <main>
-        <section id="hero">
-          <h1>Build. Scale. Succeed.</h1>
-          <p>Digital solutions for modern businesses</p>
-        </section>
-        <section id="services">...</section>
-        <section id="portfolio">...</section>
-        <section id="contact">...</section>
-      </main>
-    </>
-  );
-}
-```
-
-**What Google sees for a local business:**
-```json
-{
-  "@context": "https://schema.org",
-  "@graph": [
-    { "@type": "WebPage", "name": "Acme Solutions", "url": "https://acme.com" },
-    { "@type": "Organization", "name": "Acme Solutions", "logo": "...", "sameAs": [...] },
-    { "@type": "WebSite", "potentialAction": { "@type": "SearchAction", ... } },
-    {
-      "@type": "LocalBusiness",
-      "name": "Acme Solutions HQ",
-      "telephone": "+1-555-123-4567",
-      "address": { "@type": "PostalAddress", "streetAddress": "123 Tech Avenue", ... },
-      "geo": { "@type": "GeoCoordinates", "latitude": 37.7749, "longitude": -122.4194 },
-      "openingHours": ["Mo-Fr 09:00-18:00"]
-    }
-  ]
-}
-```
-
-### About Page
-
-```tsx
-// app/about/page.tsx — Server Component
-import {
-  toNextMetadata,
-  generateWebPageSchema,
-  generateOrganizationSchema,
-  generateBreadcrumbSchema,
-  JsonLd
-} from '@masters-ws/react-seo/core';
-
-export async function generateMetadata() {
-  return toNextMetadata({
-    title: "About Us — Our Story & Mission",
-    description: "Learn about Acme Solutions, our mission, team, and the values that drive us to build amazing digital products.",
-    image: "https://acme.com/about-og.jpg",
-    type: 'website',
-    canonical: "https://acme.com/about",
-  }, siteConfig);
-}
-
-export default function AboutPage() {
-  const schemas = [
-    generateWebPageSchema({
-      name: "About Acme Solutions",
-      description: "Our story, mission, and team",
-      url: "https://acme.com/about",
-      image: "https://acme.com/team-photo.jpg",
-    }, siteConfig),
-    generateBreadcrumbSchema([
-      { name: "Home", item: "https://acme.com" },
-      { name: "About Us", item: "https://acme.com/about" },
-    ]),
-    generateOrganizationSchema(siteConfig),
-  ];
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <main>
-        <h1>About Us</h1>
-        <p>Founded in 2020, Acme Solutions...</p>
-      </main>
-    </>
-  );
-}
-```
-
-### Services Page
-
-```tsx
-// app/services/page.tsx — Server Component
-import {
-  toNextMetadata,
-  generateWebPageSchema,
-  generateBreadcrumbSchema,
-  generateFAQSchema,
-  JsonLd
-} from '@masters-ws/react-seo/core';
-
-export async function generateMetadata() {
-  return toNextMetadata({
-    title: "Our Services — Web Development, Mobile Apps & Cloud",
-    description: "Explore our professional services: custom web development, mobile app design, cloud infrastructure, and digital consulting.",
-    image: "https://acme.com/services-og.jpg",
-    type: 'website',
-    canonical: "https://acme.com/services",
-  }, siteConfig);
-}
-
-export default function ServicesPage() {
-  const schemas = [
-    generateWebPageSchema({
-      name: "Our Services",
-      description: "Professional digital services",
-      url: "https://acme.com/services",
-    }, siteConfig),
-    generateBreadcrumbSchema([
-      { name: "Home", item: "https://acme.com" },
-      { name: "Services", item: "https://acme.com/services" },
-    ]),
-    // Add FAQ for common service questions → shows in Google rich results!
-    generateFAQSchema([
-      { q: "What technologies do you use?", a: "We specialize in React, Next.js, Node.js, and cloud platforms like AWS and GCP." },
-      { q: "How long does a typical project take?", a: "Most projects take 4-12 weeks depending on complexity." },
-      { q: "Do you offer ongoing maintenance?", a: "Yes, we offer monthly maintenance plans starting at $500/month." },
-    ]),
-  ];
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <main>
-        <h1>Our Services</h1>
-        <ServiceCard title="Web Development" description="..." />
-        <ServiceCard title="Mobile Apps" description="..." />
-        <ServiceCard title="Cloud Solutions" description="..." />
-
-        <section>
-          <h2>Frequently Asked Questions</h2>
-          {/* FAQ content */}
-        </section>
-      </main>
-    </>
-  );
-}
-```
-
-### Individual Service Page
-
-```tsx
-// app/services/[slug]/page.tsx — Server Component
-import {
-  toNextMetadata,
-  generateWebPageSchema,
-  generateBreadcrumbSchema,
-  generateHowToSchema,
-  generateFAQSchema,
-  JsonLd
-} from '@masters-ws/react-seo/core';
-
-export async function generateMetadata({ params }) {
-  const service = await fetchService(params.slug);
-
-  return toNextMetadata({
-    title: `${service.name} — Professional ${service.name} Services`,
-    description: service.meta_description,
-    image: service.og_image,
-    type: 'website',
-    canonical: `https://acme.com/services/${params.slug}`,
-  }, siteConfig);
-}
-
-export default async function ServicePage({ params }) {
-  const service = await fetchService(params.slug);
-
-  const schemas = [
-    generateWebPageSchema({
-      name: service.name,
-      description: service.description,
-      url: `https://acme.com/services/${params.slug}`,
-    }, siteConfig),
-    generateBreadcrumbSchema([
-      { name: "Home", item: "https://acme.com" },
-      { name: "Services", item: "https://acme.com/services" },
-      { name: service.name, item: `https://acme.com/services/${params.slug}` },
-    ]),
-  ];
-
-  // Add HowTo schema if the service has a process
-  if (service.process_steps) {
-    schemas.push(generateHowToSchema({
-      name: `How We Deliver ${service.name}`,
-      description: `Our step-by-step process for ${service.name}`,
-      steps: service.process_steps.map(s => ({
-        name: s.title,
-        text: s.description,
-      })),
-    }));
-  }
-
-  // Add FAQ if available
-  if (service.faqs?.length > 0) {
-    schemas.push(generateFAQSchema(
-      service.faqs.map(f => ({ q: f.question, a: f.answer }))
-    ));
-  }
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <main>
-        <h1>{service.name}</h1>
-        <div>{service.content}</div>
-      </main>
-    </>
-  );
-}
-```
-
-### Contact Page
-
-```tsx
-// app/contact/page.tsx — Server Component
-import {
-  toNextMetadata,
-  generateWebPageSchema,
-  generateBreadcrumbSchema,
-  generateLocalBusinessSchema,
-  JsonLd
-} from '@masters-ws/react-seo/core';
-
-export async function generateMetadata() {
-  return toNextMetadata({
-    title: "Contact Us — Get In Touch",
-    description: "Have a project in mind? Contact Acme Solutions for a free consultation. We respond within 24 hours.",
-    type: 'website',
-    canonical: "https://acme.com/contact",
-  }, siteConfig);
-}
-
-export default function ContactPage() {
-  const schemas = [
-    generateWebPageSchema({
-      name: "Contact Us",
-      description: "Get in touch with our team",
-      url: "https://acme.com/contact",
-    }, siteConfig),
-    generateBreadcrumbSchema([
-      { name: "Home", item: "https://acme.com" },
-      { name: "Contact", item: "https://acme.com/contact" },
-    ]),
-    generateLocalBusinessSchema({
-      name: "Acme Solutions",
-      description: "Digital solutions company",
-      telephone: "+1-555-123-4567",
-      address: {
-        street: "123 Tech Avenue",
-        city: "San Francisco",
-        region: "CA",
-        postalCode: "94105",
-        country: "US",
-      },
-      geo: { lat: 37.7749, lng: -122.4194 },
-      openingHours: ["Mo-Fr 09:00-18:00"],
-    }),
-  ];
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <main>
-        <h1>Contact Us</h1>
-        <ContactForm />
-        <Map />
-      </main>
-    </>
-  );
-}
-```
-
-### Portfolio / Case Study Page
-
-```tsx
-// app/portfolio/[slug]/page.tsx
-import {
-  toNextMetadata,
-  generateWebPageSchema,
-  generateBreadcrumbSchema,
-  JsonLd,
-  cleanSchema,
-} from '@masters-ws/react-seo/core';
-
-export async function generateMetadata({ params }) {
-  const project = await fetchProject(params.slug);
-
-  return toNextMetadata({
-    title: `${project.name} — Case Study`,
-    description: project.summary,
-    image: project.cover_image,
-    type: 'website',
-    canonical: `https://acme.com/portfolio/${params.slug}`,
-  }, siteConfig);
-}
-
-export default async function CaseStudyPage({ params }) {
-  const project = await fetchProject(params.slug);
-
-  const schemas = [
-    generateWebPageSchema({
-      name: project.name,
-      description: project.summary,
-      url: `https://acme.com/portfolio/${params.slug}`,
-      image: project.cover_image,
-      datePublished: project.completed_at,
-    }, siteConfig),
-    generateBreadcrumbSchema([
-      { name: "Home", item: "https://acme.com" },
-      { name: "Portfolio", item: "https://acme.com/portfolio" },
-      { name: project.name, item: `https://acme.com/portfolio/${params.slug}` },
-    ]),
-    // Custom CreativeWork schema for portfolio items
-    cleanSchema({
-      "@context": "https://schema.org",
-      "@type": "CreativeWork",
-      "name": project.name,
-      "description": project.summary,
-      "image": project.cover_image,
-      "dateCreated": project.completed_at,
-      "creator": {
-        "@type": "Organization",
-        "name": siteConfig.name,
-      },
-      "url": `https://acme.com/portfolio/${params.slug}`,
-    }),
-  ];
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <main>
-        <h1>{project.name}</h1>
-        <p>{project.summary}</p>
-      </main>
-    </>
-  );
-}
-```
-
-### Careers / Job Listing Page
-
-```tsx
-// app/careers/[slug]/page.tsx
-import {
-  toNextMetadata,
-  generateJobPostingSchema,
-  generateBreadcrumbSchema,
-  JsonLd
-} from '@masters-ws/react-seo/core';
-
-export async function generateMetadata({ params }) {
-  const job = await fetchJob(params.slug);
-
-  return toNextMetadata({
-    title: `${job.title} — Join Our Team`,
-    description: `We're hiring a ${job.title}. ${job.summary}`,
-    type: 'website',
-    canonical: `https://acme.com/careers/${params.slug}`,
-  }, siteConfig);
-}
-
-export default async function JobPage({ params }) {
-  const job = await fetchJob(params.slug);
-
-  const schemas = [
-    generateJobPostingSchema({
-      title: job.title,
-      description: job.full_description,
-      datePosted: job.posted_at,
-      validThrough: job.expires_at,
-      employmentType: job.type,       // "FULL_TIME", "CONTRACTOR", etc.
-      remote: job.is_remote,
-      hiringOrganization: {
-        name: siteConfig.name,
-        sameAs: siteConfig.url,
-        logo: siteConfig.logo,
-      },
-      jobLocation: {
-        streetAddress: "123 Tech Avenue",
-        addressLocality: "San Francisco",
-        addressRegion: "CA",
-        addressCountry: "US",
-      },
-      baseSalary: job.salary ? {
-        currency: "USD",
-        value: { minValue: job.salary.min, maxValue: job.salary.max },
-        unitText: "YEAR",
-      } : undefined,
-    }),
-    generateBreadcrumbSchema([
-      { name: "Home", item: "https://acme.com" },
-      { name: "Careers", item: "https://acme.com/careers" },
-      { name: job.title, item: `https://acme.com/careers/${params.slug}` },
-    ]),
-  ];
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <main>
-        <h1>{job.title}</h1>
-        <JobDetails job={job} />
-        <ApplyButton />
-      </main>
-    </>
-  );
-}
-```
-
----
-
-## 🛒 Use Case: E-Commerce Store
-
-See the [Quick Start](#-quick-start-nextjs-app-router-recommended) section above for complete examples:
-- **[Product Page](#product-page-one-call-setup)** — with reviews, return policy, shipping, variants
-- **[Category Page](#category-page-with-pagination)** — with pagination and ItemList schema
-
----
-
-## Manual Approach (More Control)
-
-Use individual functions for granular control:
-
-```tsx
-import {
-  toNextMetadata,
-  generateProductSchema,
-  generateBreadcrumbSchema,
-  generateOrganizationSchema,
-  generateWebPageSchema,
-  JsonLd
-} from '@masters-ws/react-seo/core';
-
-export async function generateMetadata({ params }) {
-  const product = await fetchProduct(params.slug);
-
-  return toNextMetadata({
-    title: product.meta_title || product.name,
-    description: product.meta_description,
-    image: product.main_image?.url,
-    type: 'product',
-    canonical: `https://store.com/products/${params.slug}`,
-    product: {
-      sku: product.sku,
-      brand: product.brand?.name,
-      price: product.price,
-      currency: "USD",
-      availability: "https://schema.org/InStock",
-    }
-  }, siteConfig);
-}
-
-export default async function ProductPage({ params }) {
-  const product = await fetchProduct(params.slug);
-
-  const schemas = [
-    generateProductSchema({
-      name: product.name,
-      description: product.description,
-      image: [product.main_image, ...product.gallery],
-      price: product.price,
-      currency: "USD",
-      url: `https://store.com/products/${params.slug}`,
-      reviews: [
-        { author: "John", ratingValue: 5, reviewBody: "Excellent product!" },
-      ],
-      returnPolicy: {
-        returnPolicyCategory: 'MerchantReturnFiniteReturnWindow',
-        returnWithin: 14,
-      },
-      shipping: {
-        shippingRate: { value: 0, currency: "USD" },
-        deliveryTime: { minDays: 2, maxDays: 5 },
-      },
-    }),
-    generateBreadcrumbSchema([
-      { name: "Home", item: "https://store.com" },
-      { name: product.name, item: `https://store.com/products/${params.slug}` },
-    ]),
-  ];
-
-  return (
-    <>
-      <JsonLd schema={schemas} graph />
-      <ProductDetailClient product={product} />
-    </>
-  );
-}
-```
-
----
-
-## `<JsonLd>` Component
-
-Server-safe JSON-LD renderer. Works in Server Components (no `'use client'` needed).
-
-### Props
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `schema` | `object \| object[]` | — | Schema object(s) to render |
-| `graph` | `boolean` | `false` | Combine schemas into a single `@graph` block |
-
-### Separate Scripts (default)
-```tsx
-<JsonLd schema={[productSchema, breadcrumbSchema]} />
-// Renders 2 separate <script type="application/ld+json"> tags
-```
-
-### @graph Pattern (recommended for multiple schemas)
-```tsx
-<JsonLd schema={[productSchema, breadcrumbSchema, orgSchema]} graph />
-// Renders 1 <script> with @context + @graph containing all schemas
-```
-
----
-
-## Usage: React / Pages Router (With Components)
-
-```tsx
-// _app.tsx
-import { SEOProvider } from '@masters-ws/react-seo';
-
-const config = { name: "My Site", url: "https://mysite.com", description: "Awesome site" };
-
-export default function App({ Component, pageProps }) {
-  return (
-    <SEOProvider config={config}>
-      <Component {...pageProps} />
-    </SEOProvider>
-  );
-}
-```
-
-```tsx
-// pages/products/[id].tsx
-import { SeoProduct } from '@masters-ws/react-seo';
-
-export default function ProductPage({ product }) {
-  return (
-    <>
-      <SeoProduct item={{
-        name: product.name,
-        description: product.description,
-        image: product.image,
-        price: product.price,
-        currency: "USD",
-        sku: product.sku,
-        brand: product.brand,
-      }} />
-      <main>...</main>
-    </>
-  );
-}
-```
-
----
-
-## Core Functions Reference
-
-### Convenience Helpers (Recommended — One-Call Setup)
-
-| Function | Description |
-| :--- | :--- |
-| `generateProductMetadata(product, config)` | Generates Metadata + Product, Breadcrumb, Organization, WebSite schemas |
-| `generateArticleMetadata(article, config)` | Generates Metadata + Article, Breadcrumb, Organization, WebSite schemas |
-| `generateCategoryMetadata(category, config)` | Generates Metadata + CollectionPage, Breadcrumb, Organization, ItemList schemas |
-| `generateHomepageMetadata(input, config)` | Generates Metadata + WebPage, Organization, WebSite, optional LocalBusiness schemas |
-
-### Metadata Functions
-
-| Function | Description |
-| :--- | :--- |
-| `toNextMetadata(data, config)` | Converts SEO data to Next.js Metadata object (OG, Twitter, Canonical, etc.) |
-| `generatePaginationLinks(url, page, total)` | Returns `prev` / `next` / `canonical` URLs |
-| `generatePaginatedTitle(title, page, suffix)` | Appends page number to title |
-
-### Schema Generator Functions
-
-| Function | Description |
-| :--- | :--- |
-| `generateProductSchema(data)` | `Product` with multi-image, reviews, return policy, shipping, variants |
-| `generateArticleSchema(data, config)` | `NewsArticle` with author and publisher |
-| `generateFAQSchema(questions)` | `FAQPage` |
-| `generateBreadcrumbSchema(items)` | `BreadcrumbList` |
-| `generateVideoSchema(data)` | `VideoObject` |
-| `generateEventSchema(data)` | `Event` (online & offline) |
-| `generateLocalBusinessSchema(data)` | `LocalBusiness` with geo and opening hours |
-| `generateOrganizationSchema(config)` | `Organization` |
-| `generateWebSiteSchema(config)` | `WebSite` with `SearchAction` |
-| `generateWebPageSchema(data, config)` | `WebPage` |
-| `generateCollectionPageSchema(data, config)` | `CollectionPage` (for categories/archives) |
-| `generateItemListSchema(data)` | `ItemList` (for product listings) |
-| `generateHowToSchema(data)` | `HowTo` with steps, tools, supplies |
-| `generateRecipeSchema(data)` | `Recipe` with ingredients and instructions |
-| `generateJobPostingSchema(data)` | `JobPosting` with salary and remote support |
-| `generateSoftwareSchema(data)` | `SoftwareApplication` |
-| `generateBookSchema(data)` | `Book` |
-| `generateMovieSchema(data)` | `Movie` |
-| `generatePodcastSchema(data)` | `PodcastSeries` |
-| `generatePodcastEpisodeSchema(data)` | `PodcastEpisode` |
-
-### Utility Functions
-
-| Function | Description |
-| :--- | :--- |
-| `cleanSchema(obj)` | Deep-removes `undefined`/`null` values from schema objects |
-| `validateSEO(type, data, fields)` | Logs dev warnings for missing required fields |
-
-### Components
-
-| Component | Description |
-| :--- | :--- |
-| `<JsonLd schema={..} graph? />` | Server-safe JSON-LD renderer with optional `@graph` support |
-
----
-
-## Product Schema Features
-
-### Multi-Image Support
-```tsx
-generateProductSchema({
-  name: "T-Shirt",
-  image: [                        // Array of images
-    "https://store.com/front.jpg",
-    "https://store.com/back.jpg",
-    "https://store.com/detail.jpg",
-  ],
-  // ...
-});
-```
-
-### Individual Reviews
-```tsx
-generateProductSchema({
-  // ...
-  rating: 4.5,
-  reviewCount: 128,
-  reviews: [
-    { author: "Alice", ratingValue: 5, reviewBody: "Amazing quality!", datePublished: "2024-01-15" },
-    { author: "Bob", ratingValue: 4, reviewBody: "Good value", datePublished: "2024-02-01" },
-  ],
-});
-```
-
-### Return Policy
-```tsx
-generateProductSchema({
-  // ...
-  returnPolicy: {
-    returnPolicyCategory: 'MerchantReturnFiniteReturnWindow',
-    returnWithin: 30,          // 30 days
-    returnMethod: 'ReturnByMail',
-    returnFees: 'FreeReturn',
-  },
-});
-```
-
-### Shipping Details
-```tsx
-generateProductSchema({
-  // ...
-  shipping: {
-    shippingRate: { value: 5.99, currency: "USD" },
-    shippingDestination: "US",
-    deliveryTime: { minDays: 3, maxDays: 7 },
-    freeShippingThreshold: 50,  // Free shipping over $50
-  },
-});
-```
-
-### Product Variants (AggregateOffer)
-```tsx
-generateProductSchema({
-  name: "T-Shirt",
-  description: "...",
-  // When variants are provided, generates AggregateOffer with lowPrice/highPrice
-  variants: [
-    { name: "Small", sku: "TS-S", price: 19.99 },
-    { name: "Medium", sku: "TS-M", price: 22.99 },
-    { name: "Large", sku: "TS-L", price: 24.99 },
-  ],
-});
-// Result: AggregateOffer { lowPrice: 19.99, highPrice: 24.99, offerCount: 3 }
-```
-
----
-
-## Development Warnings
-
-In development mode (`NODE_ENV !== 'production'`), the library logs warnings for missing required fields:
-
-```
-[react-seo] Warning: "image" is missing in Product schema. Google may not show rich results.
-[react-seo] Warning: "price" is missing in Product schema. Google may not show rich results.
-```
-
----
-
-## ⚠️ Important: SSR vs CSR
-
-### ✅ Correct — Server-Side (Google sees everything on first crawl)
-```tsx
-// page.tsx — NO 'use client'!
-import { generateProductMetadata, JsonLd } from '@masters-ws/react-seo/core';
-
-export async function generateMetadata() { /* ... */ }
-
-export default function Page() {
-  return <JsonLd schema={schemas} graph />;
-}
-```
-
-### ❌ Incorrect — Client-Side (Google may not see metadata)
-```tsx
-// page.tsx
-'use client' // ⛔ Metadata is only injected after JavaScript loads!
-
-export default function Page() {
-  return <SEO title="..." />; // Uses react-helmet → client-side only
-}
-```
-
-> **Rule of thumb:** For Next.js App Router, always use `@masters-ws/react-seo/core` functions
-> in Server Components. Use `'use client'` only for interactive UI components,
-> never for SEO logic.
-
----
-
-## Helmet Components Reference (Requires `react-helmet-async`)
-
-These components are designed for React SPA or Next.js Pages Router:
-
-| Component | Description |
-| :--- | :--- |
-| `<SEOProvider>` | Context provider — wraps your app with site config |
-| `<SEO />` | Main component for meta tags and inline schemas |
-| `<SeoArticle />` | Article/blog post SEO |
-| `<SeoProduct />` | E-commerce product SEO |
-| `<SeoFAQ />` | FAQ pages |
-| `<SeoVideo />` | Video content |
-| `<SeoEvent />` | Events and conferences |
-| `<SeoLocalBusiness />` | Physical business locations |
-| `<SeoCategory />` | Category pages with pagination |
-| `<SeoTag />` | Tag pages with pagination |
-| `<SeoAuthor />` | Author profile pages |
-| `<SeoHowTo />` | How-to guides |
-| `<SeoReview />` | Review pages |
-| `<SeoCourse />` | Online courses |
-| `<SeoRecipe />` | Recipes |
-| `<SeoJobPosting />` | Job listings |
-| `<Breadcrumb />` | Breadcrumb navigation with schema |
-
-> **Note:** `<SeoTag>`, `<SeoAuthor>`, and `<SeoCategory>` accept `pageSuffix` and `titlePrefix` props
-> for localization (defaults to English). Pass `pageSuffix="صفحة"` for Arabic, etc.
-
----
-
-## Configuration
-
-### SiteConfig
-
-```typescript
-interface SiteConfig {
-  name: string;            // Site name (used in title suffix)
-  url: string;             // Base URL (no trailing slash)
-  description: string;     // Default meta description
-  logo?: string;           // Logo URL (used in Organization schema)
-  language?: string;       // Locale, e.g. 'en_US' (default: 'ar_SA')
-  twitterHandle?: string;  // Twitter @username
-  facebookAppId?: string;  // Facebook App ID
-  themeColor?: string;     // Mobile browser theme color
-  manifest?: string;       // Web app manifest URL
-  socialLinks?: string[];  // Social media profile URLs
-  publisher?: string;      // Publisher name
-}
-```
-
-### SEOData
-
-```typescript
-interface SEOData {
-  title?: string;
-  description?: string;
-  image?: string;
-  canonical?: string;
-  type?: 'website' | 'article' | 'product' | 'profile' | 'video' | 'faq';
-  robots?: string;
-  noindex?: boolean;
-  keywords?: string[];
-  prev?: string;
-  next?: string;
-
-  // Open Graph
-  ogTitle?: string;
-  ogDescription?: string;
-  ogImage?: string;
-  ogImageWidth?: number;     // Default: 1200
-  ogImageHeight?: number;    // Default: 630
-  ogImageAlt?: string;
-  ogType?: string;
-  ogLocale?: string;
-
-  // Twitter Cards
-  twitterCard?: 'summary' | 'summary_large_image' | 'app' | 'player';
-  twitterTitle?: string;
-  twitterDescription?: string;
-  twitterImage?: string;
-
-  // Article-specific
-  publishedTime?: string;
-  modifiedTime?: string;
-  author?: { name: string; url?: string; image?: string };
-  tags?: string[];
-  section?: string;
-  readingTime?: number;
-
-  // Product-specific
-  product?: {
-    sku?: string;
-    brand?: string;
-    price?: number;
-    currency?: string;
-    availability?: string;
-    rating?: number;
-    reviewCount?: number;
-  };
-
-  // Multilingual
-  alternates?: Array<{ hreflang: string; href: string }>;
-
-  // Performance
-  dnsPrefetch?: string[];
-  preconnect?: string[];
-  prefetch?: string[];
-  preload?: Array<{ href: string; as: string; type?: string }>;
-
-  // Extras
-  whatsappImage?: string;
-  schema?: any;
-}
-```
-
----
-
-## Changelog
-
-### v1.4.0
-- ✨ **generateHomepageMetadata()** — One-call helper for homepage / landing pages
-- ✨ **cleanSchema()** — Automatically strips `undefined`/`null` from all JSON-LD output
-- ✨ **@graph pattern** — `<JsonLd graph />` combines schemas into single `@context`/`@graph` block
-- ✨ **Multi-image** — Product and Article schemas accept `string | string[]` for images
-- ✨ **Individual reviews** — Product schema supports `reviews[]` array with author, rating, body
-- ✨ **MerchantReturnPolicy** — Product schema supports return policy (category, days, method, fees)
-- ✨ **ShippingDetails** — Product schema supports shipping rate, destination, delivery time, free threshold
-- ✨ **Product variants** — Automatically generates `AggregateOffer` with `lowPrice`/`highPrice`
-- ✨ **generateCategoryMetadata()** — One-call helper for category pages with pagination + ItemList
-- ✨ **WebPage schema** — `generateWebPageSchema()` for general pages
-- ✨ **CollectionPage schema** — `generateCollectionPageSchema()` for category/archive pages
-- ✨ **ItemList schema** — `generateItemListSchema()` for product listing pages
-- ✨ **HowTo schema** — `generateHowToSchema()` with steps, tools, supplies (moved to core)
-- ✨ **Recipe schema** — `generateRecipeSchema()` (moved to core)
-- ✨ **JobPosting schema** — `generateJobPostingSchema()` with remote support (moved to core)
-- ✨ **validateSEO()** — Dev-only console warnings for missing required fields
-- 🔧 **i18n** — Removed all hardcoded Arabic strings, all labels now configurable via props
-- 🔧 **Product schema** — Added `gtin`, `mpn`, `condition`, `seller` fields
-
-### v1.3.0
-- ✨ Added `<JsonLd>` server-safe component for Next.js App Router
-- ✨ Added `generateProductMetadata()` — one-call helper for product pages
-- ✨ Added `generateArticleMetadata()` — one-call helper for article pages
-- 🔧 Enhanced `toNextMetadata()` with article OG tags, product OG tags, pagination links
-- 📝 Updated README with SSR best practices
-
-### v1.2.1
-- Initial stable release with core functions and Helmet components
-
----
-
-## 💙 Recommended: Outrank — AI-Powered SEO Platform
-
-Take your SEO to the next level with [**Outrank**](https://outrank.so/?via=shadi) — the AI-powered platform for creating SEO-optimized content at scale.
-
-- 🚀 **AI Content Generation** — Blog posts, landing pages & more
-- 📊 **SEO Analysis** — Real-time optimization suggestions  
-- ⚡ **Works great with this package** — Generate content, we handle the technical SEO
-
-🎁 **Exclusive:** Use code **`SHADI`** for **10% off** your first month.
-
-> Want to earn too? [Join the affiliate program](https://outrank.so/?via=shadi) — **30% lifetime recurring commission**.
-
----
-
-## License
-
-MIT
+[![npm version](https://img.shields.io/npm/v/@masters-ws/react-seo.svg?style=flat-square)](https://www.npmjs.com/package/@masters-ws/react-seo)
+[![Total Downloads](https://img.shields.io/npm/dt/@masters-ws/react-seo.svg?style=flat-square)](https://www.npmjs.com/package/@masters-ws/react-seo)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+# @masters-ws/react-seo
+
+> Professional SEO toolkit for React & Next.js — SSR-first, zero-dependency core, 30+ schema types, and built-in development auditor.
+
+---
+
+## Why @masters-ws/react-seo?
+
+Most SEO packages inject metadata client-side — after JavaScript loads. Google crawls your page before that. This package fixes that.
+
+| Feature | @masters-ws/react-seo | next-seo | react-helmet |
+|---|---|---|---|
+| Zero-dependency core | ✅ | ❌ | ❌ |
+| SSR-first (App Router) | ✅ | ✅ | ❌ |
+| `@graph` JSON-LD | ✅ | ❌ | ❌ |
+| One-call page setup | ✅ | ❌ | ❌ |
+| **Integrated SEO Auditor** | ✅ | ❌ | ❌ |
+| Built-in pagination SEO | ✅ | partial | ❌ |
+
+---
+
+## Installation
+
+```bash
+# Next.js App Router (zero dependencies)
+npm install @masters-ws/react-seo
+
+# React / Next.js Pages Router
+npm install @masters-ws/react-seo react-helmet-async
+```
+
+---
+
+## 🔍 SEO Auditor (Development Only)
+
+This library includes a built-in **SEO Auditor** component designed to speed up your development workflow by providing a real-time analysis of your page's SEO status directly in your browser.
+
+- **Real-Time Analysis:** Scans for title/description lengths, H1 counts, missing alt tags, and more.
+- **Visual Previews:** Live mockups for Google Search results and Social Media cards.
+- **Production Safe:** Only renders when `process.env.NODE_ENV === 'development'`.
+
+### Usage:
+
+```tsx
+// app/layout.tsx (Next.js App Router)
+import { SEOAuditor } from '@masters-ws/react-seo';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <SEOAuditor />
+      </body>
+    </html>
+  );
+}
+```
+
+---
+
+## 🚀 Quick Start: Next.js App Router (Recommended)
+
+### Product Page — One-Call Setup
+
+```tsx
+// app/products/[slug]/page.tsx
+import { generateProductMetadata, JsonLd } from '@masters-ws/react-seo/core';
+
+const siteConfig = {
+  name: "My Store",
+  url: "https://store.com",
+  logo: "https://store.com/logo.png",
+  description: "Best online store",
+  language: "en_US",
+};
+
+export async function generateMetadata({ params }) {
+  const product = await fetchProduct(params.slug);
+  const { metadata } = generateProductMetadata({
+    name: product.name,
+    description: product.short_description,
+    image: [product.main_image, ...product.gallery],
+    price: product.price,
+    currency: "USD",
+    sku: product.sku,
+    brand: product.brand?.name,
+    availability: product.in_stock
+      ? "https://schema.org/InStock"
+      : "https://schema.org/OutOfStock",
+    url: `https://store.com/products/${params.slug}`,
+    breadcrumbs: [
+      { name: "Home", item: "https://store.com" },
+      { name: product.category?.name, item: `https://store.com/categories/${product.category?.slug}` },
+      { name: product.name, item: `https://store.com/products/${params.slug}` },
+    ],
+  }, siteConfig);
+
+  return metadata;
+}
+
+export default async function ProductPage({ params }) {
+  const product = await fetchProduct(params.slug);
+  const { schemas } = generateProductMetadata({ /* same options */ }, siteConfig);
+
+  return (
+    <>
+      <JsonLd schema={schemas} graph />
+      <ProductDetailClient product={product} />
+    </>
+  );
+}
+```
+
+**What Google sees in the HTML source:**
+```html
+<title>Product Name | My Store</title>
+<meta name="description" content="..." />
+<meta property="og:title" content="Product Name" />
+<meta property="og:image" content="https://store.com/product.jpg" />
+<link rel="canonical" href="https://store.com/products/my-product" />
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@graph": [
+    { "@type": "Product", "name": "...", "offers": {...} },
+    { "@type": "BreadcrumbList", "itemListElement": [...] },
+    { "@type": "Organization", "name": "..." },
+    { "@type": "WebSite", "potentialAction": {...} }
+  ]
+}
+</script>
+```
+
+---
+
+## Core Functions
+
+### One-Call Helpers (Recommended)
+
+| Function | Generates |
+|---|---|
+| `generateProductMetadata(product, config)` | Metadata + Product, Breadcrumb, Organization, WebSite schemas |
+| `generateArticleMetadata(article, config)` | Metadata + NewsArticle, Breadcrumb, Organization, WebSite schemas |
+| `generateCategoryMetadata(category, config)` | Metadata + CollectionPage, Breadcrumb, ItemList schemas |
+| `generateHomepageMetadata(input, config)` | Metadata + WebPage, Organization, WebSite, optional LocalBusiness schemas |
+
+### Schema Generators
+
+| Function | Schema Type |
+|---|---|
+| `generateProductSchema(data)` | `Product` — multi-image, reviews, return policy, shipping, variants |
+| `generateArticleSchema(data, config)` | `NewsArticle` |
+| `generateFAQSchema(questions)` | `FAQPage` |
+| `generateBreadcrumbSchema(items)` | `BreadcrumbList` |
+| `generateLocalBusinessSchema(data)` | `LocalBusiness` |
+| `generateOrganizationSchema(config)` | `Organization` |
+| `generateWebSiteSchema(config)` | `WebSite` with `SearchAction` |
+| `generateWebPageSchema(data, config)` | `WebPage` |
+| `generateHowToSchema(data)` | `HowTo` |
+| `generateRecipeSchema(data)` | `Recipe` |
+| `generateJobPostingSchema(data)` | `JobPosting` |
+| `generateEventSchema(data)` | `Event` |
+| `generateVideoSchema(data)` | `VideoObject` |
+
+### Utilities
+
+| Function | Description |
+|---|---|
+| `toNextMetadata(data, config)` | Converts SEO data to Next.js Metadata object |
+| `cleanSchema(obj)` | Removes `undefined`/`null` from schema objects |
+| `validateSEO(type, data, fields)` | Dev-only warnings for missing required fields |
+
+### `<JsonLd>` Component
+
+```tsx
+// Multiple separate <script> tags
+<JsonLd schema={[productSchema, breadcrumbSchema]} />
+
+// Single @graph block (Google recommended)
+<JsonLd schema={[productSchema, breadcrumbSchema, orgSchema]} graph />
+```
+
+---
+
+## Product Schema — Advanced Features
+
+### Reviews + Ratings
+```tsx
+generateProductSchema({
+  name: "T-Shirt",
+  rating: 4.5,
+  reviewCount: 128,
+  reviews: [
+    { author: "Alice", ratingValue: 5, reviewBody: "Amazing quality!", datePublished: "2024-01-15" },
+    { author: "Bob",   ratingValue: 4, reviewBody: "Good value",       datePublished: "2024-02-01" },
+  ],
+});
+```
+
+### Return Policy
+```tsx
+generateProductSchema({
+  returnPolicy: {
+    returnPolicyCategory: "MerchantReturnFiniteReturnWindow",
+    returnWithin: 30,
+    returnMethod: "ReturnByMail",
+    returnFees: "FreeReturn",
+  },
+});
+```
+
+### Shipping
+```tsx
+generateProductSchema({
+  shipping: {
+    shippingRate: { value: 5.99, currency: "USD" },
+    shippingDestination: "US",
+    deliveryTime: { minDays: 3, maxDays: 7 },
+    freeShippingThreshold: 50,
+  },
+});
+```
+
+### Product Variants → AggregateOffer
+```tsx
+generateProductSchema({
+  variants: [
+    { name: "Small",  sku: "TS-S", price: 19.99 },
+    { name: "Medium", sku: "TS-M", price: 22.99 },
+    { name: "Large",  sku: "TS-L", price: 24.99 },
+  ],
+});
+// → AggregateOffer { lowPrice: 19.99, highPrice: 24.99, offerCount: 3 }
+```
+
+---
+
+## React / Pages Router
+
+```tsx
+// _app.tsx
+import { SEOProvider } from '@masters-ws/react-seo';
+
+export default function App({ Component, pageProps }) {
+  return (
+    <SEOProvider config={{ name: "My Site", url: "https://mysite.com", description: "..." }}>
+      <Component {...pageProps} />
+    </SEOProvider>
+  );
+}
+
+// pages/products/[id].tsx
+import { SeoProduct } from '@masters-ws/react-seo';
+
+export default function ProductPage({ product }) {
+  return (
+    <>
+      <SeoProduct item={{
+        name: product.name,
+        description: product.description,
+        image: product.image,
+        price: product.price,
+        currency: "USD",
+        sku: product.sku,
+      }} />
+      <main>...</main>
+    </>
+  );
+}
+```
+
+---
+
+## ⚠️ SSR vs CSR
+
+```tsx
+// ✅ Correct — Server Component, Google sees everything
+import { generateProductMetadata, JsonLd } from '@masters-ws/react-seo/core';
+export async function generateMetadata() { /* ... */ }
+export default function Page() {
+  return <JsonLd schema={schemas} graph />;
+}
+
+// ❌ Wrong — 'use client' means metadata loads after JS
+'use client';
+export default function Page() {
+  return <SEO title="..." />; // Google may miss this
+}
+```
+
+---
+
+## Generating SEO-Optimized Content
+
+This package handles technical SEO perfectly. For generating the **actual content** that ranks — blog posts, product descriptions, landing pages — pair it with [**Outrank**](https://outrank.so/?via=shadi), an AI platform built specifically for SEO content at scale.
+
+Use code **`SHADI`** for 10% off your first month.
+
+---
+
+## License
+
+MIT