WAO! Transform any webpage into an LLM-optimized interface

WAO (Web Augmentation Optimizer) is a lightweight JavaScript library that transforms any website into a structured, semantic representation optimized for Large Language Models (LLMs) acting as autonomous web agents.

• Zero-config activation - WAO stays dormant until an LLM activates it
• Visual optimizations - Transforms complex visual elements into clear, readable descriptions
• Semantic structure analysis - Automatically identifies page regions and their purpose
• Interaction mapping - Documents all possible interactions and their outcomes
• Accessibility insights - Reveals tab order, ARIA attributes, and other a11y considerations
• Data flow visualization - Maps data relationships between page elements
• Toggle between views - Easily switch between optimized and original views
• React integration - First-class support for React applications

WAO operates in two modes:

When first loaded, WAO simply injects activation instructions as DOM comments, waiting for an LLM to activate it:

<!-- 
  LLM Agent Instructions:
  - To activate this optimization library, set 'data-wao-active="true"' on the body element
  - For visual descriptions, call 'window.WAO.describeElementVisually(selector, description, elementType)'
  - To map interactions, call 'window.WAO.defineInteraction(selector, interactionType, methodName)'
  - ...and more functions documented below
-->

Once activated, WAO transforms the page by:

• Adding borders, descriptions, and semantic tags to elements
• Creating structured visual representations of page components
• Displaying interaction possibilities
• Highlighting semantic roles and importance levels
• Analyzing and displaying accessibility information

npm install @stdbl/wao

yarn add @stdbl/wao

pnpm add @stdbl/wao

Just include the script in your webpage:

<!-- UMD version -->
<script src="https://unpkg.com/@stdbl/wao/dist/index.umd.js"></script>

That's it! WAO remains dormant until an LLM activates it.

Once activated, LLMs can use these methods to better understand the page:

// Describe an element visually
window.WAO.describeElementVisually(
  '#submit-button',
  'Primary action button that submits the form data',
  'button',
  {
    role: 'submit',
    importance: 'primary',
    dataContext: 'Submits user registration information'
  }
);

// Define possible interactions
window.WAO.defineInteraction(
  '#submit-button',
  'click',
  'submitForm',
  'Validates and sends user data to the server'
);

// Describe page structure
window.WAO.describePage({
  title: 'User Registration',
  mainContent: '#registration-form',
  navigation: ['.navbar', '.breadcrumbs'],
  footer: 'footer',
  sidebar: ['.help-sidebar']
});

// Define data flows
window.WAO.describeDataFlow({
  source: '#email-input',
  destination: '#form-validator',
  dataType: 'email string',
  description: 'Email validation flow'
});

// Other helpful methods
window.WAO.extractSemanticStructure();  // Auto-detect page structure
window.WAO.analyzeAccessibility();      // Analyze accessibility features
window.WAO.highlightElementRole('#cart-button', 'shopping-cart');

WAO provides first-class React support through components and hooks:

Wrap your app with the WAO provider:

import { WAOProvider } from '@stdbl/wao/react';

function App() {
  return (
    <WAOProvider autoActivate={false}>
      <YourApp />
    </WAOProvider>
  );
}

Access WAO functionality with the useWAO hook:

import { useWAO } from '@stdbl/wao/react';

function MyComponent() {
  const { 
    isActive, 
    activate, 
    deactivate, 
    describeElement,
    analyzeAccessibility 
  } = useWAO();

  return (
    <div>
      <button onClick={activate}>
        Enable LLM Optimization
      </button>
      <button onClick={analyzeAccessibility}>
        Analyze Accessibility
      </button>
    </div>
  );
}

Use WAO's React components for declarative usage:

import { 
  WAOElement, 
  WAOToggle, 
  WAOPage, 
  WAOInspector 
} from '@stdbl/wao/react';

function ProductPage() {
  return (
    <>
      {/* Add activation toggle button */}
      <WAOToggle />
      
      {/* Define page structure */}
      <WAOPage structure={{
        title: 'Product Details',
        mainContent: '#product-details',
        navigation: ['.navbar'],
        footer: 'footer'
      }}>
        
        {/* Describe individual elements */}
        <WAOElement
          selector="#buy-now-button"
          description="Purchase button for immediate checkout"
          elementType="button"
          role="primary-action"
          importance="primary"
          interactions={[
            { type: 'click', method: 'addToCart', expectedOutcome: 'Adds item to cart and redirects to checkout' }
          ]}
        />
        
        {/* Inspector for quick accessibility/structure analysis */}
        <WAOInspector autoAnalyze={true} />
        
        {/* Your actual component content */}
        <main id="product-details">
          {/* ... */}
          <button id="buy-now-button">Buy Now</button>
        </main>
      </WAOPage>
    </>
  );
}

WAO enhances pages with several visual elements:

• Element borders - Color-coded by importance (red=primary, orange=secondary, gray=tertiary)
• Semantic tags - Blue tags showing the element type <button>
• Role indicators - Green tags showing the semantic role
• Description text - Plain-text descriptions of each element's purpose
• Interaction hints - Lists of possible interactions (click → methodName)
• Data flow arrows - Visual indicators of data relationships
• Structured panels - Fixed position panels showing page structure and accessibility info

WAO adds a toggle button to the bottom-right corner of the page, allowing easy switching between the optimized view and the original webpage.

Programmatically, you can toggle using:

// Activate
document.body.setAttribute('data-wao-active', 'true');
// or directly
window.WAO.activateOptimizer(document.body);

// Deactivate
document.body.removeAttribute('data-wao-active');
// or directly
window.WAO.deactivateOptimizer();

You can pre-configure your HTML with WAO attributes:

<button 
  id="submit" 
  data-wao-description="Primary action button"
  data-wao-role="form-submit"
  data-wao-importance="primary"
  data-wao-interaction="click:submitForm"
>
  Submit
</button>

WAO will automatically process these attributes when activated.

wao/
├── src/
│   ├── types.ts       # TypeScript interfaces
│   ├── utils.ts       # Helper functions
│   ├── core.ts        # Main library logic
│   ├── react.tsx      # React integration
│   └── index.ts       # Entry point for the library
├── dist/              # Compiled distribution files
├── package.json       # Project metadata
└── tsconfig.json      # TypeScript configuration

# Install dependencies
npm install

# Build for production
npm run build

# Development with hot reload
npm run dev

This project uses ESLint (.eslintrc.cjs) and Prettier (.prettierrc.json) with standardized configurations to ensure code quality and consistency:

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

# Run all validations (lint, format check, tests)
npm run validate

The project is configured with:

• ESLint with TypeScript and React support
• Prettier with modern configuration
• VS Code integration for automatic formatting and linting
• CI pipeline validation via GitHub Actions

VS Code users will get automatic formatting on save and linting with the provided workspace settings.

This package is published to NPM under the @stdbl organization. To publish a new version:

1. Update the version in package.json
2. Run tests and validations: pnpm validate
3. Build the package: pnpm build
4. Publish: npm publish (requires NPM authentication)

The package includes a GitHub Actions workflow to automatically publish when a new release is created:

1. Ensure your NPM token is stored as a GitHub repository secret named NPM_TOKEN
2. Create a new release on GitHub
3. The workflow will automatically build and publish the package to NPM

• LLM Web Agents - Help autonomous agents understand and interact with web UIs
• Accessibility Testing - Visualize and understand a11y structures
• UI/UX Auditing - Analyze page structure and interaction flows
• Web Scraping - Easier identification of important page elements
• Teaching Web Development - Visualize DOM structure and semantics

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ for LLMs and the humans who work with them