aeo.js 0.0.7 → 0.0.9

package/README.md

@@ -1,39 +1,22 @@
-# aeo.js
-
-Answer Engine Optimization for the modern web. Make your site discoverable by AI crawlers and LLMs.
-
 <p align="center">
-  <a href="https://ralphstarter.ai/badge"><img src="https://ralphstarter.ai/img/badge-built-with@2x.png" alt="built with ralph-starter" height="28"></a>
+  <h1 align="center">aeo.js</h1>
+  <p align="center">Answer Engine Optimization for the modern web.<br/>Make your site discoverable by ChatGPT, Claude, Perplexity, and every AI answer engine.</p>
 </p>
 
-## What is AEO?
-
-Answer Engine Optimization (AEO) is the practice of making your website discoverable and citable by AI-powered answer engines like ChatGPT, Claude, Perplexity, and SearchGPT.
-
-aeo.js auto-generates the files these engines look for and provides a drop-in widget that shows visitors how your site appears to AI.
-
-## Features
-
-- **`llms.txt` / `llms-full.txt`** -- LLM-readable summaries of your site
-- **`robots.txt`** -- AI-crawler-aware robots directives
-- **`sitemap.xml`** -- Standard sitemap generation
-- **`docs.json`** -- Structured documentation manifest
-- **`ai-index.json`** -- AI-optimized content index
-- **Raw Markdown** -- Per-page `.md` files extracted from your HTML
-- **Human/AI Widget** -- Drop-in toggle showing the AI-readable version of any page
-- **CLI** -- `npx aeo.js generate` to run standalone
+<p align="center">
+  <a href="https://www.npmjs.com/package/aeo.js"><img src="https://img.shields.io/npm/v/aeo.js?style=flat&colorA=0d0d0d&colorB=1a1a1a" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/aeo.js"><img src="https://img.shields.io/npm/dm/aeo.js?style=flat&colorA=0d0d0d&colorB=1a1a1a" alt="npm downloads"></a>
+  <a href="https://github.com/multivmlabs/aeo.js"><img src="https://img.shields.io/github/stars/multivmlabs/aeo.js?style=flat&colorA=0d0d0d&colorB=1a1a1a" alt="GitHub stars"></a>
+  <a href="https://github.com/multivmlabs/aeo.js/blob/main/LICENSE"><img src="https://img.shields.io/github/license/multivmlabs/aeo.js?style=flat&colorA=0d0d0d&colorB=1a1a1a" alt="License"></a>
+</p>
 
-## Supported Frameworks
+<p align="center">
+  <a href="https://aeojs.org">Documentation</a> · <a href="https://check.aeojs.org">AEO Checker</a> · <a href="https://www.npmjs.com/package/aeo.js">npm</a>
+</p>
 
-| Framework | Status | Import |
-|-----------|--------|--------|
-| Astro | Stable | `aeo.js/astro` |
-| Next.js | Stable | `aeo.js/next` |
-| Vite / React | Stable | `aeo.js/vite` |
-| Nuxt | Stable | `aeo.js/nuxt` |
-| Angular | Stable | `aeo.js/angular` |
-| Webpack | Stable | `aeo.js/webpack` |
-| Any (CLI) | Stable | `npx aeo.js generate` |
+<p align="center">
+  <img src="example.gif" alt="aeo.js in action" width="700">
+</p>
 
 ## Install
 
@@ -62,12 +45,8 @@ export default defineConfig({
 });
 ```
 
-The widget is automatically injected and persists across View Transitions.
-
 ### Next.js
 
-Wrap your Next.js config with `withAeo`:
-
 ```js
 // next.config.mjs
 import { withAeo } from 'aeo.js/next';
@@ -81,7 +60,7 @@ export default withAeo({
 });
 ```
 
-After building, run the post-build step to extract content from pre-rendered pages:
+Add the post-build step to `package.json`:
 
 ```json
 {
@@ -91,7 +70,7 @@ After building, run the post-build step to extract content from pre-rendered pag
 }
 ```
 
-### Vite (React, Vue, Svelte, etc.)
+### Vite
 
 ```js
 // vite.config.ts
@@ -109,16 +88,8 @@ export default defineConfig({
 });
 ```
 
-The Vite plugin:
-- Generates AEO files on `vite dev` and `vite build`
-- Injects the widget automatically
-- Serves dynamic `.md` files in dev (extracts content from your running app)
-- Detects SPA shells and falls back to client-side DOM extraction
-
 ### Nuxt
 
-Add the module to your Nuxt config:
-
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
@@ -131,17 +102,8 @@ export default defineNuxtConfig({
 });
 ```
 
-The Nuxt module:
-- Scans your `pages/` directory for routes
-- Generates AEO files during dev and production builds
-- Scans pre-rendered HTML from `.output/public/` for full page content
-- Injects the widget as a client-side Nuxt plugin
-- Adds `<link>` and `<meta>` tags for AEO discoverability
-
 ### Angular
 
-Add a post-build step to your `package.json`:
-
 ```json
 {
   "scripts": {
@@ -150,20 +112,6 @@ Add a post-build step to your `package.json`:
 }
 ```
 
-The Angular plugin:
-- Reads `angular.json` to auto-detect the output directory (`dist/<project>/browser/`)
-- Scans route config files (`*.routes.ts`) and component directories for routes
-- Scans pre-rendered HTML from the build output for full page content
-- Injects the widget into `index.html` automatically
-
-You can also generate AEO files from source routes without building:
-
-```ts
-import { generate } from 'aeo.js/angular';
-
-await generate({ title: 'My App', url: 'https://myapp.com' });
-```
-
 ### Webpack
 
 ```js
@@ -181,101 +129,39 @@ module.exports = {
 };
 ```
 
-## CLI
+### CLI
 
-Run aeo.js from the command line without any framework integration:
+No framework needed — run standalone:
 
 ```bash
-# Generate all AEO files
-npx aeo.js generate
-
-# Generate with options
-npx aeo.js generate --url https://mysite.com --title "My Site" --out public
-
-# Create a config file
+npx aeo.js generate --url https://mysite.com --title "My Site"
 npx aeo.js init
-
-# Check your setup
 npx aeo.js check
 ```
 
-### Commands
-
-| Command | Description |
-|---------|-------------|
-| `generate` | Generate all AEO files (robots.txt, llms.txt, sitemap.xml, etc.) |
-| `init` | Create an `aeo.config.ts` configuration file |
-| `check` | Validate your AEO setup and show what would be generated |
-
-### Options
-
-| Flag | Description |
-|------|-------------|
-| `--out <dir>` | Output directory (default: auto-detected) |
-| `--url <url>` | Site URL |
-| `--title <title>` | Site title |
-| `--no-widget` | Disable widget generation |
-| `--help`, `-h` | Show help |
-| `--version`, `-v` | Show version |
-
-## Configuration
-
-All framework plugins accept the same config object. You can also use `defineConfig` for standalone configs:
-
-```js
-import { defineConfig } from 'aeo.js';
-
-export default defineConfig({
-  // Required
-  title: 'My Site',
-  url: 'https://mysite.com',
-
-  // Optional
-  description: 'A description of your site',
-  contentDir: 'docs',        // Directory with handwritten .md files
-  outDir: 'public',          // Output directory for generated files
+## Supported Frameworks
 
-  // Toggle individual generators
-  generators: {
-    robotsTxt: true,          // robots.txt
-    llmsTxt: true,            // llms.txt
-    llmsFullTxt: true,        // llms-full.txt
-    rawMarkdown: true,        // Per-page .md files
-    manifest: true,           // docs.json
-    sitemap: true,            // sitemap.xml
-    aiIndex: true,            // ai-index.json
-  },
+| Framework | Import |
+|-----------|--------|
+| Astro | `aeo.js/astro` |
+| Next.js | `aeo.js/next` |
+| Vite | `aeo.js/vite` |
+| Nuxt | `aeo.js/nuxt` |
+| Angular | `aeo.js/angular` |
+| Webpack | `aeo.js/webpack` |
+| CLI | `npx aeo.js generate` |
 
-  // Customize robots.txt
-  robots: {
-    allow: ['/'],
-    disallow: ['/admin'],
-    crawlDelay: 0,
-  },
+## Widget
 
-  // Widget configuration
-  widget: {
-    enabled: true,
-    position: 'bottom-right', // 'bottom-left' | 'top-right' | 'top-left'
-    humanLabel: 'Human',
-    aiLabel: 'AI',
-    showBadge: true,
-    theme: {
-      background: 'rgba(18, 18, 24, 0.9)',
-      text: '#C0C0C5',
-      accent: '#E8E8EA',
-      badge: '#4ADE80',
-    },
-  },
-});
-```
+The Human/AI widget lets visitors toggle between the normal page and its AI-readable markdown version.
 
-## Widget
+| Default | Small | Icon |
+|---------|-------|------|
+| <img src="widget-default.gif" alt="Default widget" width="220"> | <img src="widget-small.gif" alt="Small widget" width="220"> | <img src="widget-icon.gif" alt="Icon widget" width="220"> |
 
-The Human/AI widget is a floating toggle that lets visitors switch between the normal page and its AI-readable markdown version. Framework plugins (Astro, Vite, Nuxt, Angular) inject it automatically. For Next.js or manual setups:
+Framework plugins inject it automatically. For Next.js or manual setups:
 
 ```tsx
-// app/layout.tsx (or any client component)
 'use client';
 import { useEffect } from 'react';
 
@@ -295,29 +181,98 @@ export function AeoWidgetLoader() {
 }
 ```
 
-When a visitor clicks **AI**, the widget:
-1. Fetches the `.md` file for the current page
-2. Falls back to extracting markdown from the live DOM if no `.md` exists
-3. Displays the markdown in a slide-out panel
-4. Offers copy-to-clipboard and download actions
+React and Vue wrapper components are also available:
+
+```tsx
+import { AeoReactWidget } from 'aeo.js/react';
+
+<AeoReactWidget config={{ title: 'My Site', url: 'https://mysite.com' }} />
+```
+
+```vue
+<script setup>
+import { AeoVueWidget } from 'aeo.js/vue';
+</script>
+
+<template>
+  <AeoVueWidget :config="{ title: 'My Site', url: 'https://mysite.com' }" />
+</template>
+```
 
 ## Generated Files
 
-After building, your output directory will contain:
+After building, your output directory contains:
 
 ```
 public/
-  robots.txt          # AI-crawler-aware directives
-  llms.txt            # Short LLM-readable summary
-  llms-full.txt       # Full content for LLMs
-  sitemap.xml         # Standard sitemap
-  docs.json           # Documentation manifest
-  ai-index.json       # AI-optimized content index
-  index.md            # Markdown for /
-  about.md            # Markdown for /about
-  ...                 # One .md per discovered page
+├── robots.txt        # AI-crawler directives
+├── llms.txt          # Short LLM-readable summary
+├── llms-full.txt     # Full content for LLMs
+├── sitemap.xml       # Standard sitemap
+├── docs.json         # Documentation manifest
+├── ai-index.json     # AI content index
+├── index.md          # Markdown for /
+└── about.md          # Markdown for /about
+```
+
+## Configuration
+
+```js
+import { defineConfig } from 'aeo.js';
+
+export default defineConfig({
+  title: 'My Site',
+  url: 'https://mysite.com',
+  description: 'A description of your site',
+
+  generators: {
+    robotsTxt: true,
+    llmsTxt: true,
+    llmsFullTxt: true,
+    rawMarkdown: true,
+    sitemap: true,
+    aiIndex: true,
+    schema: true,
+  },
+
+  schema: {
+    enabled: true,
+    organization: { name: 'My Company', url: 'https://mysite.com' },
+    defaultType: 'WebPage',
+  },
+
+  og: {
+    enabled: true,
+    image: 'https://mysite.com/og.png',
+    twitterHandle: '@mycompany',
+  },
+
+  widget: {
+    enabled: true,
+    position: 'bottom-right',
+    theme: { accent: '#4ADE80', badge: '#4ADE80' },
+  },
+});
 ```
 
+Full configuration reference → [aeojs.org/reference/configuration](https://aeojs.org/reference/configuration/)
+
+## Why AEO?
+
+- **58% of searches** end without a click — AI gives the answer directly
+- **40% of Gen Z** prefer AI assistants over traditional search engines
+- **97% of sites** have no `llms.txt` or structured data for AI crawlers
+- **1 minute** to set up with aeo.js
+
+If your site isn't optimized for AI engines, you're invisible to a growing share of users who never open a search results page.
+
+## Links
+
+- [Documentation](https://aeojs.org)
+- [AEO Checker](https://check.aeojs.org)
+- [npm](https://www.npmjs.com/package/aeo.js)
+- [GitHub](https://github.com/multivmlabs/aeo.js)
+
 ## License
 
 MIT

package/dist/angular.d.mts

@@ -1,4 +1,4 @@
-import { A as AeoConfig } from './types-Cn_Qbkmg.mjs';
+import { A as AeoConfig } from './types-BlLNcw-X.mjs';
 
 /**
  * Generate a widget script tag to inject into Angular's index.html.

package/dist/angular.d.ts

@@ -1,4 +1,4 @@
-import { A as AeoConfig } from './types-Cn_Qbkmg.js';
+import { A as AeoConfig } from './types-BlLNcw-X.js';
 
 /**
  * Generate a widget script tag to inject into Angular's index.html.

package/dist/angular.js

@@ -79,10 +79,19 @@ function generateRobotsTxt(config) {
   }
   lines.push("# Default for all other bots");
   lines.push("User-agent: *");
-  lines.push("Allow: /");
+  for (const path of config.robots.allow.length > 0 ? config.robots.allow : ["/"]) {
+    lines.push(`Allow: ${path}`);
+  }
+  for (const path of config.robots.disallow) {
+    lines.push(`Disallow: ${path}`);
+  }
+  if (config.robots.crawlDelay > 0) {
+    lines.push(`Crawl-delay: ${config.robots.crawlDelay}`);
+  }
   lines.push("");
-  if (config.url) {
-    lines.push(`Sitemap: ${config.url}/sitemap.xml`);
+  const sitemapUrl = config.robots.sitemap || (config.url ? `${config.url}/sitemap.xml` : "");
+  if (sitemapUrl) {
+    lines.push(`Sitemap: ${sitemapUrl}`);
   }
   lines.push("");
   lines.push("# AEO (Answer Engine Optimization) files");
@@ -164,7 +173,7 @@ function detectFramework(projectRoot = process.cwd()) {
   };
 }
 function resolveConfig(config = {}) {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, _K, _L, _M;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _A, _B, _C, _D, _E, _F, _G, _H, _I, _J, _K, _L, _M, _N;
   const frameworkInfo = detectFramework();
   return {
     title: config.title || "My Site",
@@ -208,15 +217,16 @@ function resolveConfig(config = {}) {
     widget: {
       enabled: ((_A = config.widget) == null ? void 0 : _A.enabled) !== false,
       position: ((_B = config.widget) == null ? void 0 : _B.position) || "bottom-right",
+      size: ((_C = config.widget) == null ? void 0 : _C.size) || "default",
       theme: {
-        background: ((_D = (_C = config.widget) == null ? void 0 : _C.theme) == null ? void 0 : _D.background) || "rgba(18, 18, 24, 0.9)",
-        text: ((_F = (_E = config.widget) == null ? void 0 : _E.theme) == null ? void 0 : _F.text) || "#C0C0C5",
-        accent: ((_H = (_G = config.widget) == null ? void 0 : _G.theme) == null ? void 0 : _H.accent) || "#E8E8EA",
-        badge: ((_J = (_I = config.widget) == null ? void 0 : _I.theme) == null ? void 0 : _J.badge) || "#4ADE80"
+        background: ((_E = (_D = config.widget) == null ? void 0 : _D.theme) == null ? void 0 : _E.background) || "rgba(18, 18, 24, 0.9)",
+        text: ((_G = (_F = config.widget) == null ? void 0 : _F.theme) == null ? void 0 : _G.text) || "#C0C0C5",
+        accent: ((_I = (_H = config.widget) == null ? void 0 : _H.theme) == null ? void 0 : _I.accent) || "#E8E8EA",
+        badge: ((_K = (_J = config.widget) == null ? void 0 : _J.theme) == null ? void 0 : _K.badge) || "#4ADE80"
       },
-      humanLabel: ((_K = config.widget) == null ? void 0 : _K.humanLabel) || "Human",
-      aiLabel: ((_L = config.widget) == null ? void 0 : _L.aiLabel) || "AI",
-      showBadge: ((_M = config.widget) == null ? void 0 : _M.showBadge) !== false
+      humanLabel: ((_L = config.widget) == null ? void 0 : _L.humanLabel) || "Human",
+      aiLabel: ((_M = config.widget) == null ? void 0 : _M.aiLabel) || "AI",
+      showBadge: ((_N = config.widget) == null ? void 0 : _N.showBadge) !== false
     }
   };
 }
@@ -273,7 +283,8 @@ function collectMarkdownFiles(dir, base = dir) {
     for (const entry of entries) {
       const fullPath = path.join(dir, entry);
       const stat = fs.statSync(fullPath);
-      if (stat.isDirectory() && !entry.startsWith(".") && entry !== "node_modules") {
+      const SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "public", "dist", ".next", ".nuxt", ".output", ".open-next", "coverage", "__tests__", "__mocks__"]);
+      if (stat.isDirectory() && !entry.startsWith(".") && !SKIP_DIRS.has(entry)) {
         files.push(...collectMarkdownFiles(fullPath, base));
       } else if (stat.isFile() && (path.extname(entry) === ".md" || path.extname(entry) === ".mdx")) {
         const content = fs.readFileSync(fullPath, "utf-8");
@@ -616,7 +627,8 @@ function collectUrls(dir, config, base = dir) {
     for (const entry of entries) {
       const fullPath = path.join(dir, entry);
       const stat = fs.statSync(fullPath);
-      if (stat.isDirectory() && !entry.startsWith(".") && entry !== "node_modules") {
+      const SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "public", "dist", ".next", ".nuxt", ".output", ".open-next", "coverage", "__tests__", "__mocks__"]);
+      if (stat.isDirectory() && !entry.startsWith(".") && !SKIP_DIRS.has(entry)) {
         urls.push(...collectUrls(fullPath, config, base));
       } else if (stat.isFile() && (path.extname(entry) === ".md" || path.extname(entry) === ".mdx" || path.extname(entry) === ".html")) {
         const relativePath = path.relative(base, fullPath);
@@ -844,6 +856,22 @@ function generatePageSchemas(page, config) {
       }))
     });
   }
+  if (faqItems.length === 0) {
+    const howToSteps = detectHowToSteps(page.content || "");
+    if (howToSteps.length > 0) {
+      schemas.push({
+        "@context": "https://schema.org",
+        "@type": "HowTo",
+        name: page.title || config.title,
+        step: howToSteps.map((s, i) => ({
+          "@type": "HowToStep",
+          position: i + 1,
+          name: s.name,
+          text: s.text
+        }))
+      });
+    }
+  }
   const pageType = config.schema.defaultType;
   const pageSchema = {
     "@context": "https://schema.org",
@@ -920,6 +948,34 @@ function detectFaqPatterns(content) {
   }
   return items;
 }
+function detectHowToSteps(content) {
+  const steps = [];
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    const stepMatch = line.match(/^#{1,6}\s+(?:Step\s+\d+[\s:.-]*|(\d+)[.)]\s*)(.+)$/i);
+    if (stepMatch) {
+      const name = (stepMatch[2] || stepMatch[1] || "").trim();
+      const bodyLines = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        const nextLine = lines[j].trim();
+        if (!nextLine) {
+          if (bodyLines.length > 0) break;
+          continue;
+        }
+        if (/^#{1,6}\s/.test(nextLine)) break;
+        bodyLines.push(nextLine);
+      }
+      if (name) {
+        steps.push({
+          name,
+          text: bodyLines.join(" ").slice(0, 500)
+        });
+      }
+    }
+  }
+  return steps.length >= 2 ? steps : [];
+}
 async function generateAEOFiles(configOrRoot, maybeConfig) {
   var _a;
   let config;