{
  "wwwand": {
    "standard": "wwwand-alpha",
    "version": "0.1.18",
    "minClientVersion": "0.1.18",
    "actionMode": "server"  // "server" (default) | "client" — see Client-Side Actions below
  },
  "site": {
    "name": "My App",
    "description": "A brief description Wanda reads to understand context",
    "url": "https://myapp.com"
  },
  "auth": {
    "required": true,
    "type": "bearer"  // "bearer" | "apiKey" | "none"
  },
  "intents": {
    "media": {
      "itemTerms": ["product", "item"],
      "actions": {
        "search": "search",
        "add": "addToCart"
      }
    }
  },
  "actions": [
    {
      "name": "search",
      "description": "Search for products by keyword",
      "type": "read",  // "read" | "write"
      "params": [
        { "name": "query", "type": "string", "required": true, "description": "Search term" },
        { "name": "limit", "type": "number", "required": false, "description": "Max results" }
      ]
    },
    {
      "name": "addToCart",
      "description": "Add a product to the user's cart",
      "type": "write",
      "params": [
        { "name": "productId", "type": "string", "required": true, "description": "Product identifier" }
      ]
    }
  ]
}

// Request body
{
  "action": "search",
  "params": {
    "query": "wireless headphones",
    "limit": 3
  }
}

// Success response
{
  "success": true,
  "result": {
    // Any JSON — Wanda reads this and summarises it for the user
    "items": [
      { "id": "p1", "name": "Sony WH-1000XM5", "price": "$349" }
    ]
  },
  "message": "Found 1 result"  // Optional human-readable summary
}

// Error response
{
  "success": false,
  "error": "Product not found"
}

// bearer token — passed as Authorization header
Authorization: Bearer <user_token>

// apiKey — passed as X-API-Key header
X-API-Key: <user_token>

// Server mode — manifest + action endpoint
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-API-Key

// Client mode — manifest only (actions go through the browser)
Access-Control-Allow-Origin: *

const express = require('express')
const app = express()
app.use(express.json())

const CORS = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-API-Key'
}

app.options('/.wwwand/*', (req, res) => res.set(CORS).sendStatus(204))

app.get('/.wwwand/manifest.json', (req, res) => {
  res.set(CORS).json({
    wwwand: { standard: 'wwwand-alpha', version: '0.1.18', minClientVersion: '0.1.18', actionMode: 'server' },
    site: { name: 'My App', description: 'Does something useful', url: 'https://myapp.com' },
    auth: { required: false },
    actions: [
      {
        name: 'getStatus',
        description: 'Get current app status',
        type: 'read',
        params: []
      }
    ]
  })
})

app.post('/.wwwand/action', (req, res) => {
  const { action, params } = req.body
  if (action === 'getStatus') {
    res.set(CORS).json({ success: true, result: { status: 'All systems operational' } })
  } else {
    res.set(CORS).status(400).json({ success: false, error: `Unknown action: ${action}` })
  }
})

app.listen(3000)

{
  "wwwand": {
    "standard": "wwwand-alpha",
    "version": "0.1.18",
    "minClientVersion": "0.1.18",
    "actionMode": "client",       // "client" = browser tab handles actions
    "handleUndispatched": true  // opt in to receive user text when AI skips the dispatch block
  },
  "site": { "name": "My Music", "description": "A music player with browser-local songs", "url": "https://mymusic.example" },
  "intents": {
    "media": {
      "itemTerms": ["song", "track"],
      "actions": {
        "play": "playSong",
        "stop": "stopSong",
        "pause": "pauseSong",
        "resume": "resumeSong",
        "next": "nextSong",
        "previous": "previousSong",
        "shuffle": "shuffleSongs"
      }
    }
  },
  "actions": [
    { "name": "listSongs", "description": "List all songs in the library", "type": "read", "params": [] },
    { "name": "playSong", "description": "Play a song by ID", "type": "write", "params": [{ "name": "id", "type": "string", "required": true }] },
    { "name": "stopSong", "description": "Stop playback", "type": "write", "params": [] },
    { "name": "pauseSong", "description": "Pause playback", "type": "write", "params": [] },
    { "name": "resumeSong", "description": "Resume playback", "type": "write", "params": [] },
    { "name": "nextSong", "description": "Skip to next song", "type": "write", "params": [] },
    { "name": "previousSong", "description": "Go back to previous song", "type": "write", "params": [] },
    { "name": "shuffleSongs", "description": "Shuffle the song order", "type": "write", "params": [] }
  ]
}

<script src="https://wwwand.com/wwwand-client.js"></script>

<script>
WwwandClient.onAction(async (action, params, userText) => {
  if (action === 'listSongs') {
    const songs = await getAllSongsFromIndexedDB()
    return { songs }
  }
  if (action === 'playSong') {
    // userText lets you correct dispatches — e.g. if the AI sent "play"
    // but the user actually said "next", use userText to detect that:
    if (/\bnext\b/i.test(userText)) return nextSong()
    if (/\bprevious\b/i.test(userText)) return previousSong()
    playSong(params.id)
    return { ok: true }
  }
  throw new Error(`Unknown action: ${action}`)
})
</script>

// Match against your declared intents when the AI didn't dispatch
WwwandClient.onUndispatched((userText) => {
  const lower = userText.toLowerCase()
  const terms = ['song', 'track']
  if (terms.some(t => lower.includes(t)) && /\b(play|start)\b/.test(lower)) {
    return playFirstSong() // return a result → handled
  }
  if (/\b(stop|halt)\b/.test(lower)) {
    return stopPlayback() // handled
  }
  return null // not handled — other sites may try
})

// Example: play action with autoplay fallback
WwwandClient.onAction(async (action, params, userText) => {
  if (action === 'playSong') {
    const song = getSong(params.id)
    try {
      await playInBrowser(song) // try playing in the site tab
      return { ok: true }
    } catch (e) {
      if (e.name === 'NotAllowedError') {
        // Autoplay blocked — hand off to WWWAND
        return { audioBlocked: true, dataUrl: song.dataUrl, name: song.title, id: song.id }
      }
      throw e
    }
  }
  if (action === 'stopSong') {
    // If WWWAND is playing on our behalf, tell it to stop
    WwwandClient.audioControl('stop')
    return { stopped: true }
  }
})