Changelog

New @surfjs/web package for local browser execution, CLI and dependency fixes.

• feat@surfjs/web — local/browser execution via window.surf dispatcher
• featwindow.surf global registered by @surfjs/react on mount
• fix@surfjs/cli baseUrl read from manifest execute field
• fixReplaced workspace:* references with explicit semver ranges

Version alignment, SurfBadge component, surfMiddleware for Next.js discovery.

• featSurfBadge component — holographic seal badge for Surf-enabled sites
• featsurfMiddleware for @surfjs/next — well-known discovery endpoint
• fixAll packages aligned to 0.3.9

Bug fixes: Zod 4 type detection, TS strict mode, circular ref guard, auth error handling, ESM WebSocket compat.

• fix@surfjs/zod Zod 4 type detection — all types no longer fall back to string
• fix@surfjs/zod defineZodCommand() TS strict mode compatibility
• fix@surfjs/core circular references in responses no longer crash server
• fix@surfjs/core authVerifier exceptions return structured error instead of HTML 500
• fix@surfjs/core wsHandler() now works in ESM modules (dynamic import instead of require)

Dependency alignment and minor fixes.

• fixPackage dependency alignment across all @surfjs packages

Comprehensive bug fix release — 11 issues resolved across session handling, security, and client robustness.

• fixSession expiry now returns undefined instead of throwing — prevents 500 errors on expired sessions
• fixWebSocket rate limiting — IP extraction from upgrade headers enables per-client rate limiting
• fixClient retry logic only retries transient errors (429, 502-504), not application errors
• fixResponse cache upgraded from FIFO to LRU eviction
• fixXSS fix in browserScript() — manifest JSON now sanitized against script injection
• fixESM compatibility — client WS transport uses dynamic import() instead of require()
• feathonoAppSync() — synchronous Hono adapter for Cloudflare Workers
• featregenerateManifest() on SurfInstance for dynamic command changes
• featProactive session cleanup every 60s with dispose() method

Bug fixes for auth bypass, Fastify compatibility, and CORS preflight handling.

• fixauth: true (boolean) on commands now correctly enforces authentication
• fixFastify adapter: session/start no longer fails — client sends empty JSON body
• fixCORS preflight (OPTIONS) handlers added to all adapters

Initial state delivery, React package docs, and documentation improvements.

• fixSurf Live: initial state now delivered on channel subscribe
• feat@surfjs/react added to README ecosystem section
• featExpanded documentation with guides and API reference

Adapter fixes and client improvements.

• fixHidden commands no longer leak in Fastify/Hono manifests
• fixHono adapter ESM compatibility fixed
• fixSurfClient.commands getter now works correctly

Surf Live — real-time state sync between AI agents and browser UIs via WebSocket.

• featSurf Live: channel-based state sync with version deduplication
• featWebSocket transport for full-duplex agent communication
• feat@surfjs/react — useSurfState() and useSurfEvent() hooks
• featFastify adapter with full route registration
• featHono adapter for edge runtimes (Cloudflare Workers, Deno Deploy)
• feat@surfjs/next — Next.js App Router catch-all handler
• featSSE streaming for real-time command output

Zod integration, CLI tooling, session management, and pipeline execution.

• feat@surfjs/zod — validate command params and returns with Zod schemas
• feat@surfjs/cli — test Surf-enabled sites from the terminal
• featSession management — stateful multi-step agent workflows
• featPipeline execution — batch multiple commands in a single request with $prev references
• featRate limiting — per-token, per-session, per-command limits
• featAuth middleware — Bearer token, API key, and custom auth per command

DX improvements: command examples in manifest, namespace descriptions, better validation errors, standard error codes.

• featCommand `examples` field — show sample request/response pairs in the manifest for dramatically better agent accuracy
• feat`about` field on config/manifest — longer context for agents about what the site does
• featNamespace `_description` — describe what a command group does (e.g. what `cart.*` covers)
• feat`NOT_FOUND` error code — distinct from UNKNOWN_COMMAND for "valid command, missing resource"
• featRate limit info exposed in manifest per command — agents can plan batch operations
• featCommand `tags` for categorization — filter by intent (e.g. read-only, content, interactive)
• fixValidation errors now include actual values — `expected number, got string ("abc")` for agent self-correction

Better documentation, improved CLI install guide, enhanced npm READMEs.

• featCLI README: clearer global install vs npx instructions, PATH troubleshooting
• featAll packages: npm READMEs with badges, ecosystem links, and intro copy
• featWebsite: agent prompt copy section for coding agents
• featWebsite: 4-package ecosystem grid with "when to use" guidance
• featWebsite: "What agents are saying" testimonials section
• featWebsite: Figma-like hero visualisation with switchable demo modes
• fixGitHub README links to SPEC.md and CONTRIBUTING.md now resolve

README improvements for npm pages with proper introductions and badges.

• featAll npm packages now have proper intro sections explaining what they do
• featAdded npm version, MIT license, and GitHub stars badges
• featCross-references between packages for ecosystem navigation

Initial public release. Ten packages, full protocol implementation, marketing website.

• feat@surfjs/core — server-side command registry, middleware, manifest generation
• feat@surfjs/client — agent-side SDK with discover, execute, pipeline, sessions
• feat@surfjs/cli — terminal tool: inspect, test, and ping Surf endpoints
• feat@surfjs/devui — interactive browser-based dev inspector
• featProtocol spec v0.1.0 — discovery, transports, auth, error codes
• featFramework adapters: Express, Fastify, Hono, Next.js App Router
• featPipeline execution — chain commands in a single HTTP round-trip
• featSSE streaming for long-running commands
• featWebSocket transport for real-time bidirectional communication
• featSession management with server-side state
• featAuth: Bearer, API key, OAuth2 support with per-command auth levels
• featRate limiting: global and per-command, by IP/session/auth/global

import { createSurf } from '@surfjs/core'

const surf = await createSurf({
  name: 'My Store',
  commands: {
    search: {
      description: 'Search products',
      params: { query: { type: 'string', required: true } },
      run: async ({ query }) => db.products.search(query),
    },
  },
})

app.use(surf.middleware())
// → /.well-known/surf.json + POST /surf/execute