@coherent.js/seo 1.0.0-beta.3 → 1.0.0-beta.6

package/README.md

@@ -0,0 +1,681 @@
+# @coherent.js/seo
+
+SEO optimization tools for Coherent.js applications - Meta tags, structured data, and search engine optimization utilities.
+
+## Installation
+
+```bash
+npm install @coherent.js/seo
+# or
+pnpm add @coherent.js/seo
+# or
+yarn add @coherent.js/seo
+```
+
+## Overview
+
+The `@coherent.js/seo` package provides comprehensive SEO tools for Coherent.js applications, including:
+
+- Dynamic meta tag management
+- Open Graph and Twitter Card support
+- JSON-LD structured data generation
+- Sitemap generation
+- Robots.txt management
+- SEO-friendly URL generation
+- Canonical URL support
+- Internationalization SEO
+
+## Quick Start
+
+```javascript
+import { createSEOHooks } from '@coherent.js/seo';
+
+// Create SEO hooks
+const seo = createSEOHooks();
+
+// Add to your Coherent.js component
+function BlogPost({ post }) {
+  // Set SEO metadata
+  seo.setMetadata({
+    title: `${post.title} - My Blog`,
+    description: post.excerpt,
+    keywords: post.tags,
+    author: post.author.name,
+    publishedTime: post.publishedAt,
+    image: post.featuredImage
+  });
+  
+  return {
+    div: {
+      children: [
+        { h1: { text: post.title } },
+        { div: { 
+          innerHTML: post.content,
+          className: 'post-content' 
+        }}
+      ]
+    }
+  };
+}
+```
+
+## Features
+
+### Dynamic Meta Tags
+
+Automatically generate meta tags for search engines:
+
+```javascript
+import { createSEOHooks } from '@coherent.js/seo';
+
+const seo = createSEOHooks();
+
+function ProductPage({ product }) {
+  seo.setMetadata({
+    title: product.name,
+    description: product.description,
+    keywords: [product.category, product.brand, ...product.tags],
+    image: product.images[0],
+    locale: 'en_US',
+    type: 'product',
+    url: `https://example.com/products/${product.slug}`
+  });
+  
+  return {
+    div: {
+      children: [
+        { h1: { text: product.name } },
+        { p: { text: product.description } },
+        { img: { src: product.images[0], alt: product.name } }
+      ]
+    }
+  };
+}
+```
+
+### Open Graph Support
+
+Generate Open Graph meta tags for social sharing:
+
+```javascript
+seo.setMetadata({
+  title: 'Awesome Product',
+  description: 'This product will change your life',
+  image: 'https://example.com/product-image.jpg',
+  type: 'product.item',
+  siteName: 'My E-commerce Store',
+  locale: 'en_US',
+  
+  // Open Graph specific
+  og: {
+    price: {
+      amount: '29.99',
+      currency: 'USD'
+    },
+    availability: 'instock'
+  }
+});
+```
+
+### Twitter Card Support
+
+Generate Twitter Card meta tags:
+
+```javascript
+seo.setMetadata({
+  title: 'Check out this awesome content!',
+  description: 'You won\'t believe what happens next',
+  image: 'https://example.com/twitter-card-image.jpg',
+  
+  // Twitter specific
+  twitter: {
+    card: 'summary_large_image',
+    site: '@mywebsite',
+    creator: '@author'
+  }
+});
+```
+
+### JSON-LD Structured Data
+
+Generate structured data for rich search results:
+
+```javascript
+import { createArticleSchema, createBreadcrumbSchema } from '@coherent.js/seo';
+
+function BlogPost({ post, breadcrumbs }) {
+  // Add article structured data
+  seo.addSchema(createArticleSchema({
+    headline: post.title,
+    description: post.excerpt,
+    author: {
+      name: post.author.name,
+      url: `/authors/${post.author.slug}`
+    },
+    datePublished: post.publishedAt,
+    dateModified: post.updatedAt,
+    image: post.featuredImage,
+    keywords: post.tags,
+    articleBody: post.content
+  }));
+  
+  // Add breadcrumb schema
+  seo.addSchema(createBreadcrumbSchema(breadcrumbs));
+  
+  return {
+    div: {
+      children: [
+        { h1: { text: post.title } },
+        { div: { innerHTML: post.content } }
+      ]
+    }
+  };
+}
+```
+
+## SEO Hooks
+
+### Basic Usage
+
+```javascript
+import { createSEOHooks } from '@coherent.js/seo';
+
+const seo = createSEOHooks({
+  defaultTitle: 'My Website',
+  defaultDescription: 'Welcome to my awesome website',
+  defaultImage: '/default-social-image.jpg',
+  siteUrl: 'https://example.com'
+});
+
+function Page({ title, description }) {
+  seo.setMetadata({
+    title: title,
+    description: description
+  });
+  
+  return {
+    div: {
+      children: [
+        { h1: { text: title } },
+        { p: { text: description } }
+      ]
+    }
+  };
+}
+```
+
+### Advanced Configuration
+
+```javascript
+const seo = createSEOHooks({
+  // Default metadata
+  defaultTitle: 'My Website',
+  defaultDescription: 'Default description',
+  defaultImage: '/images/default.jpg',
+  siteUrl: 'https://example.com',
+  
+  // SEO settings
+  titleTemplate: '%s | My Website', // "Page Title | My Website"
+  truncateTitle: 60,                // Truncate titles to 60 chars
+  truncateDescription: 160,         // Truncate descriptions to 160 chars
+  
+  // Social media
+  social: {
+    twitter: '@mytwitterhandle',
+    facebook: 'myfacebookpage',
+    linkedin: 'mylinkedincompany'
+  },
+  
+  // Default Open Graph
+  og: {
+    type: 'website',
+    siteName: 'My Website'
+  }
+});
+```
+
+## Sitemap Generation
+
+Generate dynamic sitemaps:
+
+```javascript
+import { createSitemap } from '@coherent.js/seo';
+
+const sitemap = createSitemap({
+  siteUrl: 'https://example.com',
+  changefreq: 'daily',
+  priority: 0.7,
+  lastmod: new Date()
+});
+
+// Add URLs to sitemap
+sitemap.add({
+  url: '/',
+  changefreq: 'daily',
+  priority: 1.0
+});
+
+sitemap.add({
+  url: '/about',
+  changefreq: 'monthly',
+  priority: 0.8
+});
+
+sitemap.add({
+  url: '/blog',
+  changefreq: 'weekly',
+  priority: 0.9
+});
+
+// Generate sitemap XML
+const sitemapXml = sitemap.toXML();
+```
+
+## Robots.txt Management
+
+Generate robots.txt files:
+
+```javascript
+import { createRobotsTxt } from '@coherent.js/seo';
+
+const robots = createRobotsTxt({
+  userAgent: '*',              // Default user agent
+  allow: ['/'],                // Allow all paths
+  disallow: ['/admin', '/private'], // Disallow specific paths
+  sitemap: 'https://example.com/sitemap.xml',
+  host: 'https://example.com'
+});
+
+// Add custom rules
+robots.addRule({
+  userAgent: 'Googlebot',
+  allow: ['/'],
+  crawlDelay: 10
+});
+
+// Generate robots.txt content
+const robotsTxt = robots.toString();
+```
+
+## Canonical URLs
+
+Manage canonical URLs to prevent duplicate content issues:
+
+```javascript
+function ProductPage({ product, queryParams }) {
+  // Set canonical URL without tracking parameters
+  const canonicalUrl = `https://example.com/products/${product.slug}`;
+  
+  seo.setCanonical(canonicalUrl);
+  
+  // Add alternate URLs for internationalization
+  seo.addAlternate({
+    href: `https://example.com/en/products/${product.slug}`,
+    hreflang: 'en'
+  });
+  
+  seo.addAlternate({
+    href: `https://example.com/es/products/${product.slug}`,
+    hreflang: 'es'
+  });
+  
+  return {
+    div: {
+      children: [
+        { h1: { text: product.name } },
+        { p: { text: product.description } }
+      ]
+    }
+  };
+}
+```
+
+## Internationalization SEO
+
+Support for multilingual SEO:
+
+```javascript
+function MultilingualPage({ content, language, translations }) {
+  // Set language
+  seo.setLanguage(language);
+  
+  // Add alternate language versions
+  Object.entries(translations).forEach(([lang, url]) => {
+    seo.addAlternate({
+      href: url,
+      hreflang: lang
+    });
+  });
+  
+  // Set direction for RTL languages
+  seo.setDirection(language === 'ar' || language === 'he' ? 'rtl' : 'ltr');
+  
+  return {
+    div: {
+      lang: language,
+      children: [
+        { h1: { text: content.title } },
+        { div: { innerHTML: content.body } }
+      ]
+    }
+  };
+}
+```
+
+## API Reference
+
+### createSEOHooks(options)
+
+Create SEO hooks for metadata management.
+
+**Parameters:**
+- `options.defaultTitle` - Default page title
+- `options.defaultDescription` - Default page description
+- `options.defaultImage` - Default social image
+- `options.siteUrl` - Base site URL
+- `options.titleTemplate` - Title template string
+- `options.truncateTitle` - Title character limit
+- `options.truncateDescription` - Description character limit
+
+**Returns:** SEO hooks object with methods
+
+### SEO Hooks Methods
+
+- `seo.setMetadata(metadata)` - Set page metadata
+- `seo.setTitle(title)` - Set page title
+- `seo.setDescription(description)` - Set page description
+- `seo.setCanonical(url)` - Set canonical URL
+- `seo.addAlternate(options)` - Add alternate language URL
+- `seo.addSchema(schema)` - Add JSON-LD schema
+- `seo.setLanguage(lang)` - Set page language
+- `seo.setDirection(dir)` - Set text direction
+
+### createSitemap(options)
+
+Create a sitemap generator.
+
+**Parameters:**
+- `options.siteUrl` - Base site URL
+- `options.changefreq` - Default change frequency
+- `options.priority` - Default priority
+- `options.lastmod` - Default last modified date
+
+**Returns:** Sitemap generator object
+
+### createRobotsTxt(options)
+
+Create a robots.txt generator.
+
+**Parameters:**
+- `options.userAgent` - Default user agent
+- `options.allow` - Allowed paths
+- `options.disallow` - Disallowed paths
+- `options.sitemap` - Sitemap URL
+- `options.host` - Host URL
+
+**Returns:** Robots.txt generator object
+
+## Schema Generators
+
+### createArticleSchema(options)
+
+Generate Article JSON-LD schema.
+
+**Parameters:**
+- `options.headline` - Article headline
+- `options.description` - Article description
+- `options.author` - Author information
+- `options.datePublished` - Publication date
+- `options.dateModified` - Modification date
+- `options.image` - Featured image
+- `options.keywords` - Article keywords
+- `options.articleBody` - Article content
+
+### createBreadcrumbSchema(breadcrumbs)
+
+Generate Breadcrumb JSON-LD schema.
+
+**Parameters:**
+- `breadcrumbs` - Array of breadcrumb objects with name and url
+
+### createProductSchema(options)
+
+Generate Product JSON-LD schema.
+
+**Parameters:**
+- `options.name` - Product name
+- `options.description` - Product description
+- `options.image` - Product images
+- `options.offers` - Product offers/pricing
+- `options.brand` - Product brand
+- `options.category` - Product category
+- `options.sku` - Product SKU
+
+## Examples
+
+### Blog with Full SEO
+
+```javascript
+import { 
+  createSEOHooks, 
+  createArticleSchema, 
+  createBreadcrumbSchema 
+} from '@coherent.js/seo';
+
+const seo = createSEOHooks({
+  siteUrl: 'https://myblog.com',
+  defaultTitle: 'My Blog',
+  titleTemplate: '%s | My Blog'
+});
+
+function BlogPost({ post }) {
+  // Set basic metadata
+  seo.setMetadata({
+    title: post.title,
+    description: post.excerpt,
+    image: post.featuredImage,
+    publishedTime: post.publishedAt,
+    modifiedTime: post.updatedAt,
+    type: 'article',
+    author: post.author.name,
+    tags: post.tags
+  });
+  
+  // Add structured data
+  seo.addSchema(createArticleSchema({
+    headline: post.title,
+    description: post.excerpt,
+    author: {
+      name: post.author.name,
+      url: `/authors/${post.author.slug}`
+    },
+    datePublished: post.publishedAt,
+    dateModified: post.updatedAt,
+    image: post.featuredImage,
+    keywords: post.tags,
+    articleBody: post.content
+  }));
+  
+  // Add breadcrumbs
+  seo.addSchema(createBreadcrumbSchema([
+    { name: 'Home', url: '/' },
+    { name: 'Blog', url: '/blog' },
+    { name: post.title, url: `/blog/${post.slug}` }
+  ]));
+  
+  // Set canonical URL
+  seo.setCanonical(`https://myblog.com/blog/${post.slug}`);
+  
+  return {
+    article: {
+      className: 'blog-post',
+      children: [
+        { h1: { text: post.title } },
+        { 
+          div: { 
+            className: 'post-meta',
+            children: [
+              { span: { text: `By ${post.author.name}` } },
+              { time: { 
+                text: formatDate(post.publishedAt),
+                datetime: post.publishedAt
+              }}
+            ]
+          }
+        },
+        { div: { 
+          className: 'post-content',
+          innerHTML: post.content 
+        }}
+      ]
+    }
+  };
+}
+```
+
+### E-commerce Product Page
+
+```javascript
+import { 
+  createSEOHooks, 
+  createProductSchema 
+} from '@coherent.js/seo';
+
+const seo = createSEOHooks({
+  siteUrl: 'https://mystore.com'
+});
+
+function ProductPage({ product, reviews }) {
+  // Basic SEO metadata
+  seo.setMetadata({
+    title: `${product.name} | My Store`,
+    description: product.description,
+    image: product.images[0],
+    type: 'product.item',
+    
+    // Open Graph for social sharing
+    og: {
+      price: {
+        amount: product.price.toString(),
+        currency: product.currency
+      },
+      availability: product.inStock ? 'instock' : 'outofstock',
+      condition: 'new'
+    },
+    
+    // Twitter Card
+    twitter: {
+      card: 'summary_large_image',
+      label1: 'Price',
+      data1: `${product.currency} ${product.price}`,
+      label2: 'Availability',
+      data2: product.inStock ? 'In Stock' : 'Out of Stock'
+    }
+  });
+  
+  // Product structured data
+  seo.addSchema(createProductSchema({
+    name: product.name,
+    description: product.description,
+    image: product.images,
+    offers: {
+      price: product.price.toString(),
+      priceCurrency: product.currency,
+      availability: product.inStock ? 'InStock' : 'OutOfStock',
+      url: `https://mystore.com/products/${product.slug}`,
+      seller: {
+        name: 'My Store'
+      }
+    },
+    brand: product.brand,
+    category: product.category,
+    sku: product.sku,
+    gtin: product.gtin,
+    aggregateRating: {
+      ratingValue: reviews.averageRating,
+      reviewCount: reviews.count
+    }
+  }));
+  
+  // Set canonical and alternates
+  seo.setCanonical(`https://mystore.com/products/${product.slug}`);
+  
+  return {
+    div: {
+      className: 'product-page',
+      children: [
+        { h1: { text: product.name } },
+        { 
+          div: { 
+            className: 'product-images',
+            children: product.images.map(img => ({
+              img: { src: img, alt: product.name }
+            }))
+          }
+        },
+        { p: { text: product.description } },
+        { p: { text: `${product.currency} ${product.price}` } },
+        { 
+          button: { 
+            text: product.inStock ? 'Add to Cart' : 'Out of Stock',
+            disabled: !product.inStock
+          }
+        }
+      ]
+    }
+  };
+}
+```
+
+## Best Practices
+
+### 1. Unique Titles and Descriptions
+
+```javascript
+// Good: Unique for each page
+seo.setMetadata({
+  title: `How to Master Coherent.js | Developer Guide`,
+  description: 'Learn advanced techniques for building high-performance Coherent.js applications with this comprehensive guide.'
+});
+
+// Avoid: Generic/duplicated content
+seo.setMetadata({
+  title: 'Page Title',
+  description: 'This is a description'
+});
+```
+
+### 2. Optimal Lengths
+
+```javascript
+// Title: 50-60 characters
+// Description: 150-160 characters
+seo.setMetadata({
+  title: 'Coherent.js Performance Optimization Guide', // 42 chars - good
+  description: 'Maximize your Coherent.js application performance with these proven optimization techniques and best practices.' // 117 chars - good
+});
+```
+
+### 3. Image Optimization
+
+```javascript
+seo.setMetadata({
+  // Use appropriately sized images
+  image: {
+    url: 'https://example.com/social-image.jpg',
+    width: 1200,
+    height: 630,
+    alt: 'Description of image content'
+  }
+});
+```
+
+## Related Packages
+
+- [@coherent.js/core](../core/README.md) - Core framework
+- [@coherent.js/i18n](../i18n/README.md) - Internationalization
+- [@coherent.js/client](../client/README.md) - Client-side utilities
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coherent.js/seo",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.6",
   "description": "SEO utilities for Coherent.js applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
   "author": "Coherent.js Team",
   "license": "MIT",
   "peerDependencies": {
-    "@coherent.js/core": "1.0.0-beta.3"
+    "@coherent.js/core": "1.0.0-beta.6"
   },
   "repository": {
     "type": "git",
@@ -35,6 +35,7 @@
     "README.md",
     "types/"
   ],
+  "sideEffects": false,
   "scripts": {
     "build": "node build.mjs",
     "clean": "rm -rf dist"

package/types/index.d.ts

@@ -3,8 +3,164 @@
  * @module @coherent.js/seo
  */
 
-// ===== Meta Builder Types =====
+import type { CoherentNode } from '@coherent.js/core';
 
+// ============================================================================
+// Meta Tag Types
+// ============================================================================
+
+/**
+ * Generic meta tag definition
+ */
+export interface MetaTag {
+  /** Meta name attribute (for standard meta tags) */
+  name?: string;
+  /** Meta property attribute (for Open Graph, etc.) */
+  property?: string;
+  /** Meta content value */
+  content: string;
+  /** HTTP-equiv attribute */
+  httpEquiv?: string;
+}
+
+/**
+ * Open Graph image configuration
+ */
+export interface OpenGraphImage {
+  /** Image URL */
+  url: string;
+  /** Image width in pixels */
+  width?: number;
+  /** Image height in pixels */
+  height?: number;
+  /** Image alt text */
+  alt?: string;
+  /** Image MIME type */
+  type?: string;
+}
+
+/**
+ * Open Graph meta configuration
+ */
+export interface OpenGraphMeta {
+  /** Page title */
+  title: string;
+  /** Page description */
+  description?: string;
+  /** Content type */
+  type?: 'website' | 'article' | 'book' | 'profile' | 'video.movie' | 'video.episode' | 'music.song' | 'music.album';
+  /** Page URL */
+  url?: string;
+  /** Image(s) for sharing */
+  image?: string | OpenGraphImage | (string | OpenGraphImage)[];
+  /** Site name */
+  siteName?: string;
+  /** Locale (e.g., 'en_US') */
+  locale?: string;
+  /** Alternate locales */
+  alternateLocales?: string[];
+  /** Audio URL */
+  audio?: string;
+  /** Video URL */
+  video?: string;
+  /** Determiner (a, an, the, auto, or empty) */
+  determiner?: 'a' | 'an' | 'the' | 'auto' | '';
+}
+
+/**
+ * Twitter Card meta configuration
+ */
+export interface TwitterMeta {
+  /** Card type */
+  card?: 'summary' | 'summary_large_image' | 'app' | 'player';
+  /** Twitter @username of website */
+  site?: string;
+  /** Twitter @username of content creator */
+  creator?: string;
+  /** Card title (defaults to og:title) */
+  title?: string;
+  /** Card description (defaults to og:description) */
+  description?: string;
+  /** Card image (defaults to og:image) */
+  image?: string;
+  /** Image alt text */
+  imageAlt?: string;
+  /** App ID for app cards */
+  appIdIphone?: string;
+  /** App ID for iPad */
+  appIdIpad?: string;
+  /** App ID for Google Play */
+  appIdGooglePlay?: string;
+}
+
+/**
+ * Comprehensive SEO configuration
+ */
+export interface SEOConfig {
+  /** Page title */
+  title: string;
+  /** Title template (e.g., '%s | My Site') */
+  titleTemplate?: string;
+  /** Page description */
+  description?: string;
+  /** Canonical URL */
+  canonical?: string;
+  /** Robots directives (e.g., 'index, follow') */
+  robots?: string;
+  /** Additional meta tags */
+  meta?: MetaTag[];
+  /** Open Graph configuration */
+  openGraph?: OpenGraphMeta;
+  /** Twitter Card configuration */
+  twitter?: TwitterMeta;
+  /** JSON-LD structured data */
+  jsonLd?: Record<string, unknown> | Record<string, unknown>[];
+  /** Keywords (comma-separated or array) */
+  keywords?: string | string[];
+  /** Author name */
+  author?: string;
+  /** Viewport settings */
+  viewport?: string;
+  /** Character set */
+  charset?: string;
+  /** Language code */
+  language?: string;
+  /** Theme color */
+  themeColor?: string;
+}
+
+// ============================================================================
+// SEO Generation Functions
+// ============================================================================
+
+/**
+ * Generate meta tags from SEO configuration
+ * @returns Array of meta element nodes
+ */
+export function generateMeta(config: SEOConfig): CoherentNode[];
+
+/**
+ * Generate JSON-LD script tag from data
+ */
+export function generateJsonLd(data: Record<string, unknown>): CoherentNode;
+
+/**
+ * Create a reusable SEO component from configuration
+ */
+export function createSEOComponent(config: SEOConfig): () => CoherentNode;
+
+/**
+ * Merge multiple SEO configurations (later configs override earlier)
+ */
+export function mergeSEOConfig(...configs: Partial<SEOConfig>[]): SEOConfig;
+
+// ============================================================================
+// Meta Builder
+// ============================================================================
+
+/**
+ * All meta tags in a flat structure
+ */
 export interface MetaTags {
   title?: string;
   description?: string;
@@ -32,41 +188,88 @@ export interface MetaTags {
   twitterDescription?: string;
   twitterImage?: string;
   // Custom meta tags
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
+/**
+ * Fluent builder for meta tags
+ */
 export class MetaBuilder {
   constructor(tags?: MetaTags);
+
+  /** Set page title */
   setTitle(title: string): this;
+
+  /** Set page description */
   setDescription(description: string): this;
+
+  /** Set keywords */
   setKeywords(keywords: string | string[]): this;
+
+  /** Set author */
   setAuthor(author: string): this;
+
+  /** Set robots directive */
   setRobots(robots: string): this;
+
+  /** Set canonical URL */
   setCanonical(url: string): this;
+
+  /** Set viewport */
   setViewport(viewport: string): this;
-  setOpenGraph(tags: Partial<MetaTags>): this;
-  setTwitterCard(tags: Partial<MetaTags>): this;
+
+  /** Set Open Graph properties */
+  setOpenGraph(tags: Partial<OpenGraphMeta>): this;
+
+  /** Set Twitter Card properties */
+  setTwitterCard(tags: Partial<TwitterMeta>): this;
+
+  /** Add a custom meta tag */
   addCustomTag(name: string, content: string, type?: 'name' | 'property'): this;
-  build(): object;
-  render(): object;
+
+  /** Build as CoherentNode */
+  build(): CoherentNode;
+
+  /** Alias for build */
+  render(): CoherentNode;
+
+  /** Convert to HTML string */
   toHTML(): string;
 }
 
+/**
+ * Create a MetaBuilder instance
+ */
 export function createMetaBuilder(tags?: MetaTags): MetaBuilder;
-export function generateMeta(tags: MetaTags): object;
 
-// ===== Sitemap Generator Types =====
+/**
+ * Generate meta nodes from flat tags
+ */
+export function generateMeta(tags: MetaTags): CoherentNode;
 
+// ============================================================================
+// Sitemap Generator
+// ============================================================================
+
+/**
+ * Sitemap entry configuration
+ */
 export interface SitemapEntry {
+  /** Page URL */
   url: string;
+  /** Last modification date */
   lastmod?: string | Date;
+  /** Change frequency */
   changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+  /** Priority (0.0 to 1.0) */
   priority?: number;
+  /** Image entries */
   images?: Array<{
     loc: string;
     title?: string;
     caption?: string;
   }>;
+  /** Video entries */
   videos?: Array<{
     thumbnail_loc: string;
     title: string;
@@ -74,30 +277,69 @@ export interface SitemapEntry {
     content_loc?: string;
     player_loc?: string;
   }>;
+  /** Alternate language versions */
+  alternates?: Array<{
+    hreflang: string;
+    href: string;
+  }>;
 }
 
+/**
+ * Sitemap generator options
+ */
 export interface SitemapOptions {
+  /** Site hostname (e.g., 'https://example.com') */
   hostname: string;
+  /** Cache time in milliseconds */
   cacheTime?: number;
+  /** XML namespaces */
   xmlNs?: Record<string, string>;
+  /** XSL stylesheet URL */
   xslUrl?: string;
 }
 
+/**
+ * Sitemap generator class
+ */
 export class SitemapGenerator {
   constructor(options: SitemapOptions);
+
+  /** Add a URL entry */
   addUrl(entry: SitemapEntry): this;
+
+  /** Add multiple URL entries */
   addUrls(entries: SitemapEntry[]): this;
+
+  /** Remove a URL entry */
   removeUrl(url: string): this;
+
+  /** Generate sitemap XML string */
   generate(): string;
+
+  /** Alias for generate */
   toXML(): string;
+
+  /** Export entries as JSON */
   toJSON(): SitemapEntry[];
 }
 
+/**
+ * Create a sitemap generator
+ */
 export function createSitemapGenerator(options: SitemapOptions): SitemapGenerator;
+
+/**
+ * Generate sitemap XML from entries
+ */
 export function generateSitemap(entries: SitemapEntry[], options: SitemapOptions): string;
 
-// ===== Structured Data Types =====
+// ============================================================================
+// Structured Data (JSON-LD)
+// ============================================================================
 
+/**
+ * Supported structured data types
+ */
 export type StructuredDataType =
   | 'Article'
   | 'BlogPosting'
@@ -115,30 +357,71 @@ export type StructuredDataType =
   | 'FAQPage'
   | 'HowTo'
   | 'VideoObject'
-  | 'ImageObject';
+  | 'ImageObject'
+  | 'SoftwareApplication'
+  | 'Course'
+  | 'JobPosting';
 
+/**
+ * Structured data object
+ */
 export interface StructuredData {
   '@context': string;
   '@type': StructuredDataType | StructuredDataType[];
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
+/**
+ * Fluent builder for structured data
+ */
 export class StructuredDataBuilder {
   constructor(type: StructuredDataType);
+
+  /** Change the schema type */
   setType(type: StructuredDataType): this;
-  setProperty(key: string, value: any): this;
-  setProperties(properties: Record<string, any>): this;
-  addToArray(key: string, value: any): this;
+
+  /** Set a single property */
+  setProperty(key: string, value: unknown): this;
+
+  /** Set multiple properties */
+  setProperties(properties: Record<string, unknown>): this;
+
+  /** Add value to an array property */
+  addToArray(key: string, value: unknown): this;
+
+  /** Build the structured data object */
   build(): StructuredData;
+
+  /** Convert to JSON string */
   toJSON(): string;
-  toJSONLD(): object;
+
+  /** Build as JSON-LD script node */
+  toJSONLD(): CoherentNode;
 }
 
-export function createStructuredData(type: StructuredDataType, properties?: Record<string, any>): StructuredDataBuilder;
-export function generateStructuredData(type: StructuredDataType, properties: Record<string, any>): StructuredData;
+/**
+ * Create a structured data builder
+ */
+export function createStructuredData(
+  type: StructuredDataType,
+  properties?: Record<string, unknown>
+): StructuredDataBuilder;
+
+/**
+ * Generate structured data object
+ */
+export function generateStructuredData(
+  type: StructuredDataType,
+  properties: Record<string, unknown>
+): StructuredData;
 
-// Helper types for common structured data
+// ============================================================================
+// Common Structured Data Types
+// ============================================================================
 
+/**
+ * Article structured data
+ */
 export interface ArticleData {
   headline: string;
   image: string | string[];
@@ -160,6 +443,9 @@ export interface ArticleData {
   mainEntityOfPage?: string;
 }
 
+/**
+ * Product structured data
+ */
 export interface ProductData {
   name: string;
   image: string | string[];
@@ -182,6 +468,9 @@ export interface ProductData {
   };
 }
 
+/**
+ * Breadcrumb structured data
+ */
 export interface BreadcrumbData {
   itemListElement: Array<{
     '@type': 'ListItem';
@@ -190,3 +479,33 @@ export interface BreadcrumbData {
     item?: string;
   }>;
 }
+
+/**
+ * Organization structured data
+ */
+export interface OrganizationData {
+  name: string;
+  url?: string;
+  logo?: string;
+  description?: string;
+  sameAs?: string[];
+  contactPoint?: {
+    '@type': 'ContactPoint';
+    telephone: string;
+    contactType: string;
+  };
+}
+
+/**
+ * FAQ Page structured data
+ */
+export interface FAQPageData {
+  mainEntity: Array<{
+    '@type': 'Question';
+    name: string;
+    acceptedAnswer: {
+      '@type': 'Answer';
+      text: string;
+    };
+  }>;
+}