@vanillaskyai/video 0.1.0

package/docs/production.md

@@ -0,0 +1,122 @@
+[← Documentation home](../README.md) · [Previous: Errors and recovery](errors.md)
+
+# Production guide
+
+Use this checklist before serving a video response to customers.
+
+## Server boundary
+
+- Keep provider keys, the system prompt, and tools on the server.
+- Authenticate the user and tenant before reading the request body.
+- Set an explicit origin allowlist. CORS is not authentication.
+- Apply per-user and per-tenant request, token, and concurrency limits.
+- Set route, model, media, and export timeouts with cancellation propagation.
+- Bound raw input size, media count, scene count, and maximum duration.
+
+Use `createVideoHandler()` for validated SSE and read
+[the security guide](security.md) for the mandatory controls.
+The handler automatically configures scene validation: it rejects unknown
+templates and fields, missing required variables, non-supplied media URLs, and
+fabricated quote-template content before a scene reaches the player.
+Applications with a custom stream adapter may authorize additional final URLs
+with `allowMediaUrl`; the callback validates URLs and does not resolve them.
+Invalid generated parts are dropped by default, after `onError` receives their
+private reason. Accepted scenes continue streaming with a safe recoverable
+diagnostic. Use `invalidPartBehavior: "fail"` only for deliberate fail-fast behavior.
+
+## Data and privacy
+
+- Send the provider only the source and personalization required for the story.
+- Do not log raw prompts, personalization, authorization headers, signed URLs,
+  or provider deltas.
+- Record request IDs, model ID, duration, event counts, safe error codes, token
+  usage, and acceptance metrics.
+- Review your provider's retention settings and data-processing terms.
+- Keep signed asset URLs valid for the expected viewing and replay window.
+
+## Reliability
+
+- Emit the supplied opening and selected audio before starting model work.
+- Abort provider work when the client disconnects.
+- Persist terminal snapshots for replay and export, then validate loaded values
+  with `parseVideo` before use.
+- Persist event logs when resume is required; validate them with
+  validate stored event logs before replay.
+- Treat the [persistence contract](persistence.md) as the storage boundary;
+  database, tenant policy, object storage, deletion, and URL expiry remain
+  host-owned.
+- Use idempotency keys around durable generation requests.
+- Retry only before visible output or from a validated resume point. Do not
+  silently restart a response after the viewer has begun watching.
+
+## Failure experience
+
+- Keep private provider details in `onError`; send only safe typed errors.
+- Do not display stack traces or protocol diagnostics inside the video.
+- Hold the current scene and continue audio through a recoverable generation
+  gap.
+- End cleanly on a terminal error; never append blank media after completion.
+- Provide a normal application retry control outside the player.
+
+## Media and audio
+
+- Start generated playback with an asset-free scene.
+- Preload media for the next scene and commit it only when ready.
+- Resolve media before generation and pass approved results through
+  `suppliedMedia`. Stock-keyword resolution is not part of the 0.1 handler.
+- Use customer-approved media domains and enforce type/byte limits.
+- Select soundtrack audio from an already-loaded catalog; declare a positive
+  fade-out. Narration and speech synchronization are application-owned.
+- Respect browser autoplay rules and provide an explicit unmute control.
+
+## Observability
+
+Track at minimum:
+
+- time to supplied opening;
+- time to first generated scene;
+- time to complete plan;
+- seconds of future content buffered;
+- planner and protocol error codes;
+- media readiness failures;
+- completion and abandonment rate;
+- provider model and token usage.
+
+Use the repository acceptance harness in smoke tests. The defaults
+require an opening within 250 ms, a generated scene within 15 seconds,
+completion within 30 seconds, resolved media, audio before the opening, three
+body scenes, three distinct templates, and a human quality score of 80.
+
+## Testing
+
+Use the React-free deterministic helpers in [Test integrations](testing.md) for
+Vitest, in-process streaming, and route-handler tests without a live provider.
+
+Test the public path at its HTTP boundary. Pass a deterministic `streamText`
+generator to `createVideoHandler`, call the route with grounded input, and
+assert the validated terminal result through `useVideo`. Keep separate
+component tests for each trusted template.
+
+In CI, build and test the application. If the project owns copied templates,
+also verify that its registry is current:
+
+```bash
+npx vanillasky sync --check
+npm run build
+npm test
+```
+
+Before release, build one clean consumer from the packed SDK tarball. This
+catches missing exports, React/server boundary leaks, code-generation drift,
+and dependency-resolution problems that workspace tests cannot detect.
+
+## Deployment checklist
+
+- [ ] Provider keys exist only in the server secret store.
+- [ ] Authentication, tenant policy, rate limits, and origin allowlist are live.
+- [ ] Cancellation, timeouts, and safe errors are tested.
+- [ ] Every installed template renders in both orientations.
+- [ ] Chromium, Firefox, WebKit, React, and Node compatibility checks pass.
+- [ ] A real provider run passes latency and human quality review.
+- [ ] Final snapshots replay exactly and export through the configured adapter.
+- [ ] Package and application dependency audits meet your severity policy.

package/docs/prompt-and-input.md

@@ -0,0 +1,185 @@
+[← Documentation home](../README.md) · [Next: Generate your first video →](getting-started.md)
+
+# Prompt and input
+
+VanillaSky separates application truth from visual direction. You provide the
+facts and your server-side model. VanillaSky supplies the planner contract that
+turns those facts into a finite sequence of trusted scenes.
+
+## The four layers
+
+### 1. VanillaSky system prompt
+
+`createVideoHandler` generates `systemPrompt` from the trusted template
+registry. It tells the model:
+
+- which templates and variables exist;
+- how to emit the typed plan;
+- how to order and time complete scenes;
+- how to stay inside the factual and media boundaries;
+- how to finish a finite response.
+
+Normal applications should not build, copy, or expose this prompt in browser
+code. Pass it unchanged to the provider adapter.
+
+For maintainers, the base system rules live in
+`src/server/prompts/system-prompt.ts`, request-context formatting lives in
+`src/server/prompts/user-prompt.ts`, and template-specific catalog guidance
+lives in `src/visual-system/catalog/prompt.ts`. See the
+[architecture map](architecture.md) for the complete request flow.
+
+### 2. Application instructions
+
+Use `instructions` for optional presentation direction:
+
+```ts
+video.generate({
+  input: "Account alerts launched today. They refresh every 15 minutes.",
+  instructions: "Make the launch feel direct and energetic. End with adoption.",
+});
+```
+
+Instructions can influence selection, emphasis, ordering, tone, and pacing.
+They never expand the factual boundary, authorize a new media URL, or weaken
+the event and validation contract.
+
+For durable product-wide direction, use the server handler's `basePrompt`.
+Keep per-request creative direction in `instructions`.
+
+### 3. Grounded input
+
+`input` is required and is the complete factual source for the video. It may be
+plain text or a serialized structured object:
+
+```ts
+video.generate({
+  input: "Activation increased from 41% to 58% after guided onboarding.",
+});
+```
+
+```ts
+video.generate({
+  input: JSON.stringify({
+    period: "Q2",
+    activation: { previous: 41, current: 58 },
+    cause: "guided onboarding",
+  }),
+});
+```
+
+Include exact numbers, quote wording, attribution, names, dates, and product
+facts that may appear on screen. Do not place secrets, provider keys, or hidden
+policy in input.
+
+`personalization`, `brand`, and `suppliedMedia` are separate structured context.
+They do not replace the source material.
+
+### 4. Streamed plan
+
+Your provider streams text deltas. VanillaSky decodes them into typed planner
+parts, validates each complete scene, and emits deterministic protocol events.
+The model never returns React, HTML, CSS, or executable JavaScript.
+
+Generated `scene.add`, `scene.patch`, and `asset.patch` operations all pass
+through the same merged-scene validation before the player sees them.
+
+## What reaches the LLM
+
+The provider adapter receives:
+
+```ts
+streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
+  model,
+  system: systemPrompt,
+  prompt: userPrompt,
+  abortSignal: signal,
+})
+```
+
+`userPrompt` is assembled by VanillaSky from:
+
+- orientation and maximum duration;
+- whether an opening scene already exists;
+- raw `input`;
+- creative `instructions`;
+- personalization;
+- descriptions and opaque references for approved supplied media;
+- brand context.
+
+Provider credentials and application authentication never belong in either
+prompt. Original supplied-media URLs and data URIs also remain outside the
+model prompt; the server restores an exact SDK-issued opaque reference only
+after provider output has been parsed.
+
+Generated template values are validated exactly. VanillaSky does not silently
+truncate factual labels to satisfy a layout schema because truncation can drop
+qualifiers or change meaning. A rejected generated scene contributes to
+`rejectedSceneCount`; hosts can use the completion quality fields to retry with
+a stronger model or revised source.
+
+## Input examples
+
+### Product update
+
+```ts
+video.generate({
+  input: "Account alerts launched on August 16. They refresh every 15 minutes, filter by segment, and are available to all plans.",
+});
+```
+
+### Metrics recap
+
+```ts
+video.generate({
+  input: JSON.stringify({
+    period: "Q2",
+    customerConversations: 142,
+    escalationsResolved: "96%",
+    improvementsLaunched: 4,
+  }),
+  personalization: { firstName: "Joris" },
+});
+```
+
+### Grounded review
+
+```ts
+video.generate({
+  input: 'Review by Maya Chen, VP Product: "Setup took minutes, not weeks." Rating: 5/5.',
+});
+```
+
+Every visible quote must occur in the input exactly. Attribution and ratings
+should be explicit.
+
+### Article or long source
+
+Pass the source text and let the planner select the most decision-relevant
+takeaways that fit the duration. The planner summarizes; it should not attempt
+to place every paragraph on screen.
+
+## Grounding and media safety
+
+- Numeric templates require real numbers present in the source.
+- Every grounded quote value must occur in the source, not merely one quote in a scene.
+- Screenshot fields require an exact supplied image.
+- Media URLs must be supplied or approved by the server's `allowMediaUrl` policy.
+- Patches are validated after merging with the existing scene.
+
+These checks happen at runtime. Prompt instructions improve model behavior but
+are not treated as a security boundary.
+
+## Debugging
+
+If the plan is rejected or the result is weak, inspect the boundary in this order:
+
+1. **Input:** Does it contain the exact facts, numbers, quotes, and attribution?
+2. **Instructions:** Are they presentation guidance rather than new claims?
+3. **Provider adapter:** Does it pass both prompts unchanged and stream only text deltas?
+4. **Finish reason:** Did the provider report `length`, a content filter, or an execution error?
+5. **Template fit:** Does the trusted registry contain a suitable visual for the requested story?
+
+Log request IDs, provider finish reasons, and terminal SDK status. Do not log
+secrets or expose raw provider diagnostics inside the video.
+
+[← Documentation home](../README.md) · [Next: Generate your first video →](getting-started.md)

package/docs/provider-integration.md

@@ -0,0 +1,115 @@
+[← Documentation home](../README.md) · [Previous: Next.js](integrate-nextjs.md) · [Next: Input and first scene →](input-and-first-scene.md)
+
+# Provider integration
+
+The model connection enters the SDK through `streamText` in
+`src/server/create-video-handler.ts`. The SDK does not instantiate or choose a
+model; the application passes the generated `systemPrompt` and `userPrompt` to
+its provider here.
+
+Use the AI SDK as the normal app-owned provider adapter. Any AI SDK
+`LanguageModel` works. Keep selection in one server-only module so OpenAI and
+Anthropic use the same route and React component:
+
+```ts
+import "server-only";
+import { anthropic } from "@ai-sdk/anthropic";
+import { openai } from "@ai-sdk/openai";
+import { streamText } from "ai";
+import { createVideoHandler } from "@vanillaskyai/video/server";
+
+const provider = process.env.VIDEO_PROVIDER;
+const modelId = process.env.VIDEO_MODEL;
+if (!modelId) throw new Error("Set VIDEO_MODEL in the server environment");
+const model = provider === "openai" ? openai(modelId)
+  : provider === "anthropic" ? anthropic(modelId)
+    : (() => { throw new Error("Set VIDEO_PROVIDER to openai or anthropic"); })();
+
+export const POST = createVideoHandler({
+  authorize: verifySession,
+  streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
+    model,
+    system: systemPrompt,
+    prompt: userPrompt,
+    abortSignal: signal,
+  }),
+});
+```
+
+The AI SDK result can be returned directly: its `textStream`, `finishReason`,
+`rawFinishReason`, usage, provider metadata, warnings, and response metadata
+match VanillaSky's structural callback contract. Keep the
+provider, model, and credentials on the server. The callback runs per request,
+so an application can route cheap/fast and high-capability models through the
+same handler without adding a VanillaSky abstraction. See
+[provider adapter reference](reference/provider-adapters.md) for model alternatives and advanced native
+provider loops.
+
+## Completion and usage
+
+Use `onComplete` for server-side cost and completion measurement:
+
+```ts
+createVideoHandler({
+  authorize: verifySession,
+  streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
+    model,
+    system: systemPrompt,
+    prompt: userPrompt,
+    abortSignal: signal,
+  }),
+  onWarning: (warning) => logSafeWarning(warning.code, warning.category),
+  onComplete: (summary) => recordGeneration({
+    finishReason: summary.finishReason,
+    usage: summary.usage,
+    requestedModelId: summary.requestedModelId,
+    resolvedModelId: summary.resolvedModelId,
+    totalDurationMs: summary.totalDurationMs,
+  }),
+  onError: (error) => recordPrivateFailure(error),
+});
+```
+
+`onComplete` fires once only after `response.complete`. It does not fire for a
+terminal error, abort, disconnect, or timeout. Callback failures are isolated
+from the event stream. Normalized token usage and model IDs remain server-only;
+they never enter SSE or the persisted `Video`. Set `includeRawProviderData:
+true` only when the host deliberately needs bounded provider-native usage and
+metadata and has an appropriate retention policy.
+
+`acceptedSceneCount`, `rejectedSceneCount`, and `timeToFirstSceneMs` describe
+model-generated scene additions; a deterministic supplied opening is not
+counted. Their sum is the proposed scene count. `videoDurationSec` is the
+duration actually committed; compare it with the `maxDurationSec` supplied by
+your application when applying a retry policy. These fields provide a
+server-side quality signal without exposing model metadata in the browser.
+Warnings include the same bounded typed warnings emitted to the client.
+For non-interactive backfills, define an application threshold (for example,
+no rejected scenes and a useful committed-duration ratio) and retry a bounded
+number of times. Keep the best accepted result rather than treating
+`finishReason: "stop"` alone as a quality score.
+
+The generated system prompt includes the selected trusted-template catalog and
+is intentionally substantial. It is stable for the same SDK version, template
+kit, media policy, and base prompt. Record input-token usage, keep the selected
+kit no broader than the product needs, and enable provider-side prompt caching
+where the chosen provider/model supports it. VanillaSky does not assume one
+provider's cache controls in its provider-neutral adapter. With the 28 built-in
+templates, the current catalog prompt is roughly 28,000 characters (about
+7,000 tokens before user input; tokenizer-dependent); provider-reported usage
+is the authoritative measurement.
+
+Provider finish reasons `error` and `tool-calls` are terminal failures.
+`length` and `content-filter` may complete with already accepted scenes; a
+truncation before the first generated scene fails instead of returning an empty
+success. The request signal is forwarded to the provider. Configure route and
+provider timeouts with that signal, and keep retries host-owned and within the
+same explicit request budget.
+
+## Product-level planner guidance
+
+`createVideoHandler` constructs the planner prompt from the generated server
+template registry. Normal integrations do not build prompts or capabilities.
+Use the handler's `basePrompt` option only for durable product-level direction.
+Grounded facts still come from `VideoInput.input`; presentation guidance must
+never override that factual boundary.

package/docs/reference/protocol.md

@@ -0,0 +1,96 @@
+# Video Response Protocol 0.4
+
+## Transport
+
+The public transport is UTF-8 Server-Sent Events returned from a `POST` request.
+Responses use `Content-Type: text/event-stream`,
+`x-vanillasky-video-stream: 0.4`, `Cache-Control: no-cache, no-transform`, and
+`X-Accel-Buffering: no`. Each block has an SSE `id`, the event name
+`video`, and one JSON envelope in `data`. A final `data: [DONE]`
+closes the transport after a terminal protocol event. Comment heartbeats do not
+change protocol state.
+
+## Envelope
+
+```ts
+type VideoEvent<T extends string, D> = {
+  protocolVersion: "0.4";
+  runId: string;
+  sequence: number;
+  eventId: string;        // exactly `${runId}:${sequence}`
+  type: T;
+  data: D;
+};
+```
+
+Sequences start at zero and increase by exactly one. Unknown fields are
+rejected. Replaying the same `eventId` with identical content is idempotent;
+replaying it with different content is an error. A run ID cannot change
+midstream and events cannot follow a terminal state.
+
+## Lifecycle
+
+1. `response.start` establishes request ID, orientation, style, and negotiated
+   templates/extensions.
+2. Optional `audio.set` occurs at most once and before the first scene.
+3. `scene.add` appends one trusted-template scene at revision `0`.
+4. `scene.patch` or `asset.patch` advances that scene revision by exactly one.
+   A host must reject patches after the scene has played.
+5. Exactly one terminal event ends the run:
+   `response.complete`, terminal `response.error`, or `response.abort`.
+
+`response.complete` carries the complete replayable `Video`, a
+finish reason, and a deterministic checksum. The reducer verifies that the
+snapshot equals the state produced by all prior events. The checksum detects
+accidental drift; it is not a cryptographic signature.
+
+The terminal snapshot carries persisted `schemaVersion: "0.1"`. That storage
+version is independent from this streaming protocol version. Load stored
+snapshots through the universal `parseVideo` boundary described in the
+[persistence guide](../persistence.md).
+
+Recoverable `response.error` events may be followed by more events. Terminal
+errors contain a safe public message. Provider details belong only in a private
+server callback.
+
+### Duration ceiling
+
+`maxDurationSec` is enforced by the runtime for scene additions and timing
+patches. A final scene may be shortened to the remaining duration. If a later
+scene would start at the ceiling, the runtime preserves the partial response
+and emits `response.complete` with `finishReason: "length"`; reaching the
+declared maximum is normal completion, not a generation error. The value is a
+ceiling, not a target: a grounded response may complete below that ceiling when
+the source does not support another distinct readable scene.
+
+## Extensions
+
+Extension events use a namespaced `data.*` type, for example
+`data.customer.status`. They are accepted only when the exact name was
+negotiated in `response.start.capabilities.extensions`. Extensions cannot
+change core video state.
+
+## Planning boundary
+
+LLMs do not emit public protocol envelopes. A server-only planner emits
+validated `scene.add`, `scene.patch`, `asset.patch`, `plan.complete`, or
+`plan.error` parts. The runtime assigns sequences, revisions, IDs, terminal
+snapshots, and checksums. Generated HTML, React, JavaScript, CSS, component
+source, audio events, protocol envelopes, and unknown part types are rejected.
+
+## Resume
+
+A resume request repeats the public input and includes:
+
+```json
+{"resume":{"runId":"run-123","afterSequence":7}}
+```
+
+It also sends `Last-Event-ID: run-123:7`. The server validates that both cursors
+match, then calls customer-owned replay storage. Replay begins at sequence `8`
+and remains subject to normal run, order, validation, and terminal rules. The
+SDK does not prescribe or operate a persistence service.
+
+Validate adapter output and persisted replay logs against this protocol before
+accepting them. A replay log must preserve ordering, checksums, and a terminal
+event.

package/docs/reference/provider-adapters.md

@@ -0,0 +1,158 @@
+# Secure LLM provider adapters
+
+This page covers the planner boundary. For Pexels and other visual providers,
+read [Media and audio](../media-and-audio.md#media-providers).
+
+VanillaSky deliberately does not depend on a model provider or AI framework.
+Your server owns the model and credentials; `createVideoHandler` accepts one
+small `streamText` callback. The recommended adapter is the [AI SDK](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text),
+which gives the application one `LanguageModel` interface across official,
+community, AI Gateway, OpenAI-compatible, and custom providers.
+
+## Recommended: AI SDK
+
+Install the AI SDK plus the provider package your application chooses:
+
+```bash
+npm install ai @ai-sdk/openai
+```
+
+```ts
+import { openai } from "@ai-sdk/openai";
+import { streamText } from "ai";
+import { createVideoHandler } from "@vanillaskyai/video/server";
+
+const modelId = process.env.OPENAI_MODEL;
+if (!modelId) throw new Error("Set OPENAI_MODEL in the server environment");
+
+export const POST = createVideoHandler({
+  authorize: verifySession,
+  streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
+    model: openai(modelId),
+    system: systemPrompt,
+    prompt: userPrompt,
+    abortSignal: signal,
+  }),
+});
+```
+
+Return the AI SDK `StreamTextResult` directly. It is structurally compatible
+with VanillaSky's callback: VanillaSky reads `textStream`, finish metadata,
+usage, safe provider warnings, provider metadata, and response/final-step model
+metadata. Usage and model IDs are available only through the server-side
+`onComplete` summary. Provider-native usage and metadata require the explicit
+bounded `includeRawProviderData` opt-in and never enter SSE. The forwarded abort
+signal cancels provider work when the request disconnects or the host timeout
+fires.
+
+Only the model expression changes:
+
+- Use any [official AI SDK provider](https://ai-sdk.dev/providers/ai-sdk-providers).
+- Use an [AI Gateway model ID](https://ai-sdk.dev/providers/ai-sdk-providers/ai-gateway).
+- Use an [OpenAI-compatible provider](https://ai-sdk.dev/providers/openai-compatible-providers).
+- Use a [community or custom provider](https://ai-sdk.dev/providers/community-providers)
+  implementing the Language Model Specification.
+
+The callback runs for every video request, so the application may select a
+different model each time. A product can route routine planning to a cheap,
+fast model and reserve a stronger model for difficult inputs without changing
+VanillaSky or its protocol. The same boundary also accepts a self-hosted model
+or a provider-native async text stream when it is not represented in the AI
+SDK. VanillaSky has no model allowlist.
+
+The provider must emit NDJSON text: one complete VanillaSky plan part per line.
+The SDK buffers arbitrary text chunks until a newline, parses the completed
+object, validates it, and only then forwards it to the motion runtime. Do not
+replace that per-line validator with whole-response structured output: motion
+streaming intentionally renders the first scene before the full composition is
+complete.
+
+## Advanced: native provider loops
+
+Use the lower-level callback directly when the AI SDK does not expose a
+provider-specific feature you need. `streamText` may return either an
+`AsyncIterable<string>` or an object with `textStream` plus optional
+`finishReason`, `rawFinishReason`, `usage`, `providerMetadata`, and
+response/final-step metadata. Requested model IDs are read from the final
+step's `model.modelId`; resolved IDs are read from response metadata. Prefer the
+richer form when the native provider exposes completion metadata.
+
+Provider retries remain host-owned. Retry only within an explicit request and
+time budget, and never silently restart after visible output unless the host
+has validated durable resume storage.
+
+### OpenAI Responses API
+
+```ts
+import OpenAI from "openai";
+import { createVideoHandler } from "@vanillaskyai/video/server";
+
+const apiKey = process.env.OPENAI_API_KEY;
+const model = process.env.OPENAI_MODEL;
+if (!apiKey || !model) throw new Error("Set OPENAI_API_KEY and OPENAI_MODEL");
+
+const openai = new OpenAI({ apiKey });
+
+export const POST = createVideoHandler({
+  authorize: verifySession,
+  streamText: async function* ({ systemPrompt, userPrompt, signal }) {
+    const stream = await openai.responses.create({
+      model,
+      input: [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userPrompt },
+      ],
+      stream: true,
+    }, { signal });
+
+    for await (const event of stream) {
+      if (event.type === "response.output_text.delta") yield event.delta;
+    }
+  },
+});
+```
+
+OpenAI documents the typed `response.output_text.delta` event in its
+[Responses streaming guide](https://developers.openai.com/api/docs/guides/streaming-responses).
+
+### Anthropic Messages API
+
+```ts
+import Anthropic from "@anthropic-ai/sdk";
+import { createVideoHandler } from "@vanillaskyai/video/server";
+
+const apiKey = process.env.ANTHROPIC_API_KEY;
+const model = process.env.ANTHROPIC_MODEL;
+if (!apiKey || !model) throw new Error("Set ANTHROPIC_API_KEY and ANTHROPIC_MODEL");
+
+const anthropic = new Anthropic({ apiKey });
+
+export const POST = createVideoHandler({
+  authorize: verifySession,
+  streamText: async function* ({ systemPrompt, userPrompt, signal }) {
+    const stream = anthropic.messages.stream({
+      model,
+      max_tokens: 4096,
+      system: systemPrompt,
+      messages: [{ role: "user", content: userPrompt }],
+    }, { signal });
+
+    for await (const event of stream) {
+      if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
+        yield event.delta.text;
+      }
+    }
+  },
+});
+```
+
+Anthropic documents `content_block_delta` and `text_delta` in its
+[Messages streaming guide](https://platform.claude.com/docs/en/build-with-claude/streaming).
+
+## Optional web fetch and other tools
+
+Keep tools server-side and outside the SDK core. Fetch or search before motion
+generation, append only the approved grounded result to `input`, and
+record provenance separately. Apply domain allowlists, SSRF protection,
+timeouts, redirect limits, and response-size limits. Do not give a model a
+general-purpose fetch tool unless the application truly needs one.