Speed up progressive snapshots and add completion events

.changeset/faster-progressive-snapshots.md

@@ -0,0 +1,12 @@
+---
+"schema-stream": minor
+---
+
+Reduce progressive parsing overhead by batching internal partial-string updates at source-chunk
+boundaries when completion callbacks are unused, using safe fast property writes, and materializing
+`iterate()` snapshots directly without a UTF-8 JSON round trip. External and exotic defaults retain
+the previous JSON normalization behavior. Add the low-overhead `onValueComplete` event for
+child-before-parent completion deltas with their completed values while preserving the legacy
+progress callback. Add a polished Bun and Node benchmark, complex completion coverage, runnable
+examples, server-to-browser transport guidance, and deterministic plus opt-in live SDK integration
+tests, including a guarded Mastra Agent compatibility example and weekly live canary.

.github/workflows/live-e2e.yml

@@ -0,0 +1,58 @@
+name: Live model E2E
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "23 15 * * 3"
+
+concurrency:
+  group: live-model-e2e
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  openai:
+    if: github.repository == 'hack-dance/schema-stream'
+    name: ${{ matrix.provider }} live stream
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - provider: agents
+            agents-model: gpt-5.6-luna
+            mastra-model: unused
+          - provider: mastra
+            agents-model: unused
+            mastra-model: openai/gpt-5.6-luna
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.14
+
+      - name: Setup Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 24
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run live structured-output matrix
+        run: bun run test:live
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          SCHEMA_STREAM_AGENTS_MODEL: ${{ matrix.agents-model }}
+          SCHEMA_STREAM_LIVE_E2E: "1"
+          SCHEMA_STREAM_LIVE_PROVIDER: ${{ matrix.provider }}
+          SCHEMA_STREAM_MASTRA_MODEL: ${{ matrix.mastra-model }}

CONTRIBUTING.md

@@ -4,14 +4,16 @@ Thanks for helping improve Schema Stream.
 
 ## Setup
 
-Install the repository toolchain with [mise](https://mise.jdx.dev/) and install dependencies with Bun:
+Install the repository toolchain with [mise](https://mise.jdx.dev/) and install dependencies with
+Bun:
 
 ```sh
 mise install
 bun install
 ```
 
-The repository develops with Bun 1.3.14, Node.js 24, and TypeScript 7. Consumers do not need TypeScript 7; the packed-package test verifies the published declarations with TypeScript 5.9.
+The repository develops with Bun 1.3.14, Node.js 24, and TypeScript 7. Consumers do not need
+TypeScript 7; the packed-package test verifies the published declarations with TypeScript 5.9.
 
 ## Development checks
 
@@ -28,7 +30,44 @@ For behavior changes, also inspect coverage:
 bun run test:coverage
 ```
 
-`bun run test:packed` builds and installs the package tarball into isolated ESM and CommonJS consumers. It verifies Zod 3, Zod 4, Zod Mini, OpenAI Agents SDK, Vercel AI SDK, and TypeScript 5.9 compatibility.
+`bun run test:packed` builds and installs the package tarball into isolated ESM and CommonJS
+consumers. It verifies Zod 3, Zod 4, Zod Mini, OpenAI Agents SDK, Mastra, Vercel AI SDK, and
+TypeScript 5.9 compatibility.
+
+Run the credential-free examples and SDK runtime integrations when changing stream adapters or
+public examples:
+
+```sh
+bun run examples
+bun test tests/sdk-runtime.test.ts
+```
+
+The opt-in live provider matrix fails closed when explicitly enabled without its required model and
+credential variables. See [`docs/integration-testing.md`](./docs/integration-testing.md) for secure
+runtime injection, provider selection, and the exact verification contract.
+
+## Benchmarking
+
+Run the Bun and Node snapshot benchmark after changes to parser hot paths, snapshot materialization,
+or emission policies:
+
+```sh
+bun run benchmark
+```
+
+The default command builds the local package, validates every measured result, and prints compact
+median comparisons. Use `bun run benchmark --verbose` for ranges and emission details, or
+`bun run benchmark --json` to retain raw samples. Use `bun run benchmark --help` to narrow fixtures,
+policies, runtimes, and payload sizes.
+
+Use `bun run benchmark --completion-scaling` when completion callback behavior changes. It compares
+no callback, `onValueComplete`, and legacy `onKeyComplete` as nested record counts double without
+adding the cumulative-history workload to the default benchmark.
+
+Keep runtime versions, fixture size, source chunk size, warmups, repetitions, and policy selection
+identical when comparing revisions. Do not present isolated `JSON.stringify` or `JSON.parse` timings
+as feature-equivalent SchemaStream competitors. Publish representative numbers only with their full
+configuration and retain machine-readable evidence when making a performance claim.
 
 ## Changes
 
@@ -41,4 +80,5 @@ bun run test:coverage
 bun run changeset
 ```
 
-See [`AGENTS.md`](./AGENTS.md) for the complete project conventions, testing matrix, and public-OSS privacy rules.
+See [`AGENTS.md`](./AGENTS.md) for the complete project conventions, testing matrix, and public-OSS
+privacy rules.