Architecture

web-ai-sdk has a narrow scope. This page defines package boundaries and the rules for adding a capability.

One package per browser capability

Each @web-ai-sdk/* package wraps one browser capability:

Package	Wraps
@web-ai-sdk/prompt	LanguageModel
@web-ai-sdk/webmcp	document.modelContext
@web-ai-sdk/summarizer	Summarizer
@web-ai-sdk/translator	Translator
@web-ai-sdk/detector	LanguageDetector
@web-ai-sdk/writer	Writer
@web-ai-sdk/rewriter	Rewriter
@web-ai-sdk/proofreader	Proofreader
@web-ai-sdk/all	Meta-package; re-exports the wrappers above

One package = one capability. If a package has two independent jobs, split it.

The built-in APIs have different options and result types. WebMCP is an agent interface, not a model. A single model abstraction cannot represent these differences.

Published SDK packages do not import from each other. Application code composes capabilities when needed.

When a capability enters the SDK

Public evidence and wrapper value determine when a capability enters the SDK:

Stage	SDK treatment
Tracked	A public proposal exists, but public information is not sufficient for an implementation. Track it in an issue.
Preview	Public instructions expose a runnable capability. A lifecycle wrapper adds clear value. An experimental 0.x package can ship.
Trial	A public developer or origin trial is available. Keep the package 0.x while expanding browser coverage and demos.
Stable	A stable browser exposes the capability without a flag or token. Package 1.0 remains a separate decision.
Retired	The proposal is withdrawn or replaced. Deprecate the package and document migration rather than repurposing it.

Preview requires all of these conditions:

• an authoritative public source with enough information to test the capability;
• one cohesive package boundary;
• lifecycle value beyond types, such as feature detection, session reuse, cleanup, abort handling, or stream normalization;
• zero runtime dependencies, deterministic tests, and a deliberate unsupported-browser behavior;
• no persistence, cross-capability composition, or unrelated algorithms.

All published claims must use public sources. Do not publish confidential preview details. Keep the capability Tracked when public evidence is not sufficient.

Preview and Trial describe browser maturity. They do not reduce package quality requirements. See the contributor checklist.

Zero-dependency policy

Each @web-ai-sdk/* package has no runtime dependencies. react is the only allowed optional peer dependency.

• The browser APIs already change often. Dependencies add another source of change.
• Transitive dependencies add security and maintenance risk.
• Installing one wrapper should not install unrelated libraries.

Features that need a third-party runtime belong outside these core wrappers.

Vanilla trunk, React adapter as a subpath

Every package has two entry points:

// Vanilla: TypeScript / DOM only, framework-agnostic.
import { ask, createSession } from "@web-ai-sdk/prompt";

// React: small hook adapter that wraps the vanilla core.
import { usePrompt, useSession } from "@web-ai-sdk/prompt/react";

The vanilla entry is the source of truth. The React entry connects the vanilla API to hook lifecycles. Both entries ship in one package.

Future framework adapters must use a subpath such as @web-ai-sdk/<pkg>/<framework>. The framework must be an optional peer.

Defaults and application policy

The SDK can provide defaults within one capability. For example, Prompt provides:

• Session reuse. ask() reuses compatible base sessions. Use createSession() when you need direct lifecycle control.
• Optional result caching. Pass "session", "local", or a custom { get, set } cache. Caching is off by default.
• Stream normalization. onUpdate receives cumulative text. sendStreaming() yields deltas.

Each default:

• stays within one capability;
• can be disabled or replaced;
• handles lifecycle code that consumers would otherwise repeat.

The SDK does not compose capabilities, walk the DOM, render UI, or add runtime dependencies. Application code owns those concerns.

Summary

The SDK has one package per browser capability. Each package has no runtime dependencies and handles lifecycle only.

In scope for the SDK	Out of scope
Wraps one browser capability	Composes two or more capabilities
Lifecycle: feature detection, session cache, abort, error wrapping	Retries, history, rendering, persistence
Ergonomic defaults inside one capability (LRU cache, stream smoothing)	Walks or mutates the DOM beyond what the platform API does
Zero runtime dependencies	Anything that needs a third-party runtime dependency

New browser capabilities can become new packages after they pass the adoption policy. Application code owns reusable cross-capability workflows.