hints: { execution: 'browser' }  // Always handled locally
hints: { execution: 'server' }   // Always goes to server
hints: { execution: 'any' }      // Runtime picks (default)

const surf = await createSurf({
  name: 'Acme Store',
  commands: {
    search: {
      description: 'Search products by query',
      params: {
        query: { type: 'string', required: true },
        maxPrice: { type: 'number' },
        category: { type: 'string', enum: ['electronics', 'clothing', 'books'] },
      },
      returns: { type: 'array', items: { $ref: '#/types/Product' } },
      hints: { idempotent: true, sideEffects: false, estimatedMs: 200 },
      run: async ({ query, maxPrice, category }) => {
        return db.products.search(query, { maxPrice, category });
      },
    },
  },
});

import { SurfClient } from '@surfjs/client';

const client = await SurfClient.discover('https://acme-store.com');
const results = await client.execute('search', { query: 'blue shoes', maxPrice: 100 });

import express from 'express';
import { createSurf } from '@surfjs/core';

const app = express();
app.use(express.json());
const surf = await createSurf({ name: 'My App', commands: { /* ... */ } });
app.use(surf.middleware());

import Fastify from 'fastify';
import { createSurf } from '@surfjs/core';
import { fastifyPlugin } from '@surfjs/core/fastify';

const surf = await createSurf({ name: 'My App', commands: { /* ... */ } });
const app = Fastify();
app.register(fastifyPlugin(surf));

import { Hono } from 'hono';
import { createSurf } from '@surfjs/core';
import { honoApp } from '@surfjs/core/hono';

const surf = await createSurf({ name: 'My App', commands: { /* ... */ } });
const app = new Hono();
const surfApp = await honoApp(surf);
app.route('/', surfApp);

import { honoMiddleware } from '@surfjs/core/hono';
export default { fetch: await honoMiddleware(surf) };

// app/api/surf/surf-instance.ts
import { createSurf } from '@surfjs/core';
export const surf = await createSurf({ name: 'My App', commands: { /* ... */ } });

// app/api/surf/route.ts — GET /.well-known/surf.json (use next.config rewrite)
import { NextResponse } from 'next/server';
import { surf } from './surf-instance';
export async function GET() {
  return NextResponse.json(surf.manifest());
}

// app/api/surf/execute/route.ts — POST /api/surf/execute
import { NextRequest, NextResponse } from 'next/server';
import { surf } from '../surf-instance';
export async function POST(request: NextRequest) {
  const { command, params, sessionId } = await request.json();
  const response = await surf.commands.execute(command, params, { sessionId });
  return NextResponse.json(response, { status: response.ok ? 200 : 500 });
}

{
  description: 'What this command does',
  params: {
    name: { type: 'string', required: true, description: 'User name' },
    count: { type: 'number', default: 10 },
    category: { type: 'string', enum: ['a', 'b', 'c'] },
    tags: { type: 'array', items: { type: 'string' } },
    options: { type: 'object', properties: { verbose: { type: 'boolean' } } },
  },
  returns: { type: 'object', properties: { id: { type: 'string' } } },
  tags: ['search', 'products'],
  auth: 'required',        // 'none' | 'required' | 'optional' | 'hidden'
  hints: {
    idempotent: true,       // Safe to retry
    sideEffects: false,     // Read-only
    estimatedMs: 200,       // Expected latency
  },
  stream: true,             // Enable SSE streaming
  rateLimit: { windowMs: 60000, maxRequests: 10, keyBy: 'ip' },
  run: async (params, context) => {
    // context.sessionId, context.auth, context.claims, context.state
    // context.emit (streaming only), context.ip, context.requestId
    return result;
  },
}

const surf = await createSurf({
  name: 'My App',
  commands: {
    cart: {
      add: { description: 'Add to cart', run: async (params) => { /* ... */ } },
      remove: { description: 'Remove from cart', run: async (params) => { /* ... */ } },
      checkout: { description: 'Checkout', run: async (params) => { /* ... */ } },
    },
    user: {
      profile: { description: 'Get profile', run: async () => { /* ... */ } },
    },
  },
});
// → Commands: cart.add, cart.remove, cart.checkout, user.profile

const surf = await createSurf({
  name: 'My App',
  auth: { type: 'bearer', description: 'JWT token' },
  authVerifier: async (token, command) => {
    const user = await verifyJwt(token);
    return user
      ? { valid: true, claims: { userId: user.id, role: user.role } }
      : { valid: false, reason: 'Invalid token' };
  },
  commands: {
    publicSearch: {
      description: 'Public search',
      auth: 'none',     // No auth required
      run: async (params) => { /* ... */ },
    },
    getProfile: {
      description: 'Get user profile',
      auth: 'required', // Must authenticate
      run: async (params, ctx) => {
        // ctx.claims.userId available here
      },
    },
    getRecommendations: {
      description: 'Get recommendations',
      auth: 'optional', // Personalized if authenticated
      run: async (params, ctx) => {
        if (ctx.claims) { /* personalized */ }
      },
    },
    adminDashboard: {
      description: 'Admin analytics dashboard',
      auth: 'hidden',   // Not in manifest unless authed
      run: async (params, ctx) => { /* ... */ },
    },
  },
});

import { bearerVerifier } from '@surfjs/core';
const surf = await createSurf({
  authVerifier: bearerVerifier(['token-1', 'token-2']),
  // ...
});

const surf = await createSurf({
  name: 'My App',
  rateLimit: { windowMs: 60_000, maxRequests: 100, keyBy: 'ip' }, // Global
  commands: {
    expensiveOp: {
      description: 'Resource-heavy operation',
      rateLimit: { windowMs: 60_000, maxRequests: 5, keyBy: 'auth' }, // Per-command override
      run: async (params) => { /* ... */ },
    },
  },
});

// Server — use context.state and context.sessionId
run: async ({ sku }, ctx) => {
  const cart = ctx.state?.cart ?? [];
  cart.push(sku);
  ctx.state = { ...ctx.state, cart };
  return { cartSize: cart.length };
}

// Client — start/use/end sessions
const session = await client.startSession();
await session.execute('addToCart', { sku: 'SHOE-001' });
await session.execute('addToCart', { sku: 'HAT-002' });
const cart = await session.execute('getCart');
await session.end();

const results = await client.pipeline([
  { command: 'search', params: { query: 'shoes' }, as: 'results' },
  { command: 'getProduct', params: { id: '$results[0].id' } },
  { command: 'addToCart', params: { sku: '$results[0].sku' } },
]);
// results.results → [{ command, ok, result }, ...]

// POST /surf/pipeline
{
  "steps": [...],
  "sessionId": "optional-session",
  "continueOnError": true  // Continue executing steps even if one fails
}

const surf = await createSurf({
  name: 'AI Writer',
  commands: {
    generate: {
      description: 'Generate text with streaming',
      params: { prompt: { type: 'string', required: true } },
      stream: true,
      run: async ({ prompt }, { emit }) => {
        for (const token of generateTokens(prompt)) {
          emit!({ token });    // → SSE chunk event
          await sleep(50);
        }
        return { done: true }; // → SSE done event
      },
    },
  },
});

const response = await fetch('https://example.com/surf/execute', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ command: 'generate', params: { prompt: 'Hello' }, stream: true }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
// SSE format: data: {"type":"chunk","data":{...}}\n\n
// Final:      data: {"type":"done","result":{...}}\n\n

import { createServer } from 'http';
const server = createServer(app);
surf.wsHandler(server); // Requires the 'ws' package
server.listen(3000);

const ws = await client.connect(); // Connects to ws://host/surf/ws
ws.on('orderUpdate', (data) => console.log('Order updated:', data));
const result = await ws.execute('search', { query: 'shoes' });
await ws.startSession();
await ws.endSession();
ws.close();

const script = surf.browserScript(); // Returns <script> with window.__surf__
const bridge = surf.browserBridge(); // Returns bridge code for in-page agents

import { WindowTransport } from '@surfjs/client';

const transport = new WindowTransport();
await transport.connect(); // Uses window.__surf__
const manifest = transport.discover();
const result = await transport.execute('search', { query: 'shoes' });
transport.on('event', (data) => console.log(data));

import type { SurfMiddleware } from '@surfjs/core';

const logger: SurfMiddleware = async (ctx, next) => {
  console.log(`→ ${ctx.command}`, ctx.params);
  const start = Date.now();
  await next();
  console.log(`← ${ctx.command} (${Date.now() - start}ms)`);
};

const rateLimiter: SurfMiddleware = async (ctx, next) => {
  if (isRateLimited(ctx.context.ip)) {
    ctx.error = { ok: false, error: { code: 'RATE_LIMITED', message: 'Too many requests' } };
    return;
  }
  await next();
};

surf.use(logger);
surf.use(rateLimiter);

const surf = await createSurf({
  name: 'My App',
  types: {
    Product: {
      type: 'object',
      description: 'A product in the catalog',
      properties: {
        id: { type: 'string' },
        name: { type: 'string' },
        price: { type: 'number' },
      },
    },
  },
  commands: {
    search: {
      description: 'Search products',
      returns: { type: 'array', items: { $ref: '#/types/Product' } },
      run: async () => { /* ... */ },
    },
  },
});

const surf = await createSurf({
  name: 'My App',
  events: {
    'order.updated': {
      description: 'Order status changed',
      scope: 'session',  // Only the user who placed the order sees updates
      data: { orderId: { type: 'string' }, status: { type: 'string' } },
    },
    'maintenance.scheduled': {
      description: 'System maintenance announcement',
      scope: 'global',   // Everyone sees this
      data: { message: { type: 'string' }, scheduledAt: { type: 'string' } },
    },
  },
  commands: { /* ... */ },
});

// Server-side: emit with session context
surf.events.on('order.updated', (data) => { /* server-side listener */ });
surf.emit('order.updated', { orderId: '123', status: 'shipped' });

// Session cleanup on disconnect
surf.events.removeSession(sessionId);

import { createSurf } from '@surfjs/core';
import { createDevUI } from '@surfjs/devui';

const surf = await createSurf({ name: 'My App', commands: { /* ... */ } });
const devui = createDevUI(surf, { port: 4242 });

// Standalone server
const { url } = await devui.start();
console.log(`DevUI at ${url}`);  // → http://localhost:4242/__surf

// Or as Express middleware
app.use(devui.middleware());  // Mounts at /__surf