---
type: "TechArticle"
softwareVersion: "1.0.0"
url: "https://registry.docsloth.dev/components/event-stream.html"
markdown: "https://registry.docsloth.dev/docs/event-stream.md"
component: "event-stream"
section: "connected"
trust_class: "connected"
implementation_status: "implemented_native"
renderer: "native block"
install: "docsloth component add @docsloth/event-stream@1.0.0"
spec: "packages/contracts/component-specs/event-stream.md"
props_schema: "packages/contracts/component-props/event-stream.schema.json"
---

> Index: [Agent index](https://registry.docsloth.dev/llms.txt)

# event-stream

Inspect an authorized event stream

| Field | Value |
| --- | --- |
| Trust class | connected |
| Implementation status | implemented_native |
| Renderer | native block |
| Key prop (production schema) | resource |
| Key prop (protocol fixture) | streamId |
| Tools | subscribe, pause |
| Package version | 1.0.0 |
| Package digest | sha256:562d76e0327281cf0148e93323ff4ccbdcb4bfd48fcee7fe363c359c888fa77e |

## Install

```sh
docsloth component add @docsloth/event-stream@1.0.0
```

Live package: sha256:562d76e0327281cf0148e93323ff4ccbdcb4bfd48fcee7fe363c359c888fa77e with 2 file digest(s); the catalog entry is generated from the built package, not a placeholder.

## Props

The prop schema is normative in `packages/contracts/component-props/event-stream.schema.json`.

| Prop | Type | Required | Constraints |
| --- | --- | --- | --- |
| `title` | string | no | maxLength: 160 |
| `resource` | object | yes | additionalProperties: false |
| `resource.resource_id` | string | yes | format: uuid |
| `resource.operation` | string | yes | maxLength: 160 |
| `resource.environment` | "test" \| "staging" \| "production" | yes |  |
| `schema_ref` | string | yes | maxLength: 256 |
| `max_buffer_events` | integer | yes |  |
| `redacted_fields` | array<string> | yes |  |

Example props generated from this schema:

```json
{
  "title": "example-title",
  "resource": {
    "resource_id": "00000000-0000-4000-8000-000000000000",
    "operation": "example-operation",
    "environment": "test"
  },
  "schema_ref": "example-schema_ref",
  "max_buffer_events": 1,
  "redacted_fields": [
    "example-redacted_fields"
  ]
}
```

Required props: resource, schema_ref, max_buffer_events, redacted_fields.

## Example

Example document IR (the block the renderer consumes):

```json
{
  "type": "event-stream",
  "props": {
    "title": "example-title",
    "resource": {
      "resource_id": "00000000-0000-4000-8000-000000000000",
      "operation": "example-operation",
      "environment": "test"
    },
    "schema_ref": "example-schema_ref",
    "max_buffer_events": 1,
    "redacted_fields": [
      "example-redacted_fields"
    ]
  }
}
```

Renderer HTML (entities decoded and wrapped for display):

```html
<section class="ds-block ds-event-stream" data-component="event-stream" aria-labelledby="b-title">
<h3 class="ds-block-title" id="b-title">example-title</h3>
<dl class="ds-facts">
<div>
<dt>Event schema</dt>
<dd>
<code>example-schema_ref</code>
</dd>
</div>
<div>
<dt>Events buffered</dt>
<dd>1</dd>
</div>
<div>
<dt>Redacted fields</dt>
<dd>
<code>example-redacted_fields</code>
</dd>
</div>
<div>
<dt>Runs</dt>
<dd>
<code>example-operation</code> in the test environment</dd>
</div>
</dl>
<p class="ds-live-note" role="note">Subscribing to this event stream needs the live documentation site.</p>
</section>
```

Preview (interface-only; the markup above is the same output):

The renderer resolves this component as a native block; the preview above is its real HTML output, and Markdown parity for native blocks is covered by the renderer test suite.

## Specification

Generated from `packages/contracts/component-specs/event-stream.md`.

### Contract

Production props are normative in `../contracts/component-props/event-stream.schema.json`. The corresponding `component-fixtures` manifest is only a minimal protocol fixture; use the production props schema when building the published package. The packaged artifact ships exactly its generated `component-package.json` manifest plus `props.schema.json` (the production props schema, copied byte-for-byte) and `spec.md` (this spec, copied byte-for-byte); it contains no executable payload, fallback implementation, Storybook, test suite, SSR harness or README. Rendering behavior and the acceptance cases below belong to the renderer and the repository tests, not to the package. Installation pins the package version and the digest of every shipped byte.

### Intended behavior

Bounded stream with disconnect, pause and dropped-events indicator.

### Failure and fallback

Backpressure drops oldest display events with count, not unlimited RAM.

### Required acceptance cases

Authorization revocation closes stream promptly. Also test empty data, loading, denied access, browser without JS, mobile 360px, keyboard navigation, dark mode and an explicit constrained agent tool call. The server independently authorizes capability requests; a package manifest cannot grant authority.

### Data and maintenance

Data bindings resolve from a specific publication/release vector and permitted fact/evidence graph. Configuration edits create versioned component patches. Update invalidation uses dependency IDs, never indiscriminate whole-page regeneration. Human-owned props survive automatic updates unless invalidated with an explicit conflict. Missing optional resources leave an honest inert/readable fallback, not a broken page or fake success.

### Cost and tools

Pure/local interaction must never invoke a model by accident. Any model, remote query or executor call must reserve approved budget before dispatch. Public visitors do not inherit owner resources. The component may call only named tools in its signed manifest with valid typed inputs. A cancelled job stops polling and closes resources. No component gets platform administration, raw credentials or an unlimited execution loop.

### React host integration

Production resource/operation/environment, schema reference, 1–500 buffered events and redacted field paths select `ComponentContentProvider.eventStreams` through `eventStreamKey`. At most 64 unique dotted paths (256 characters and 8 segments each) are accepted; numeric segments address array entries. Available records bind the exact release, resource, schema reference/version, reader session, buffer count and sorted redaction paths.

Connecting is explicit. The typed host `subscribe` adapter receives that scope, an AbortSignal and `onFrame`, then returns a matching connected result with a close callback. Each event or terminal frame repeats the exact scope. Event frames must attest `redaction: applied` and `schemaValidation: passed`; the host must actually enforce audience permissions and the referenced versioned schema before delivery. These flags are host claims, not independent client schema validation. Transport buffering, authorization checks throughout a subscription, credential handling, remote query budgets and prompt revocation remain host responsibilities. No generic executor or model call is issued by the component.

The renderer admits zoned valid timestamps and detached JSON payloads only. Each payload is bounded to depth 8, 1000 visited nodes, 64 keys per object, 128 array entries and 4096 UTF-16 units per string; the complete retained event must fit 16 KiB of UTF-8 JSON. Configured paths are replaced before retention, and common credential/email/IP patterns receive display masking. This is defense in depth, not a guarantee of complete PII detection: private data must never be sent to the browser in the first place. Unknown frame/event metadata is discarded.

A live buffer drops the oldest events beyond the configured count or 128 KiB of serialized UTF-8 events, with a dropped count. Duplicate IDs still in the buffer are ignored. Display updates run at most every 100 ms instead of queuing React work for every incoming event. Pause freezes the displayed event snapshot; the connection continues, the live buffer remains bounded, and the drop count continues to update. The paused display can retain a second bounded snapshot. Resume shows the latest retained events. Disconnect closes the local connection and preserves last received content. A fresh connection clears prior history; there is no automatic reconnect or claim that unobserved events were recovered.

Permission revocation clears both displayed and buffered events and aborts/closes the subscription, including while paused. Invalid frames, changed scope, unmount and late connection acknowledgements also clean up old resources. Cleanup errors cannot produce unhandled rejections; the host must honor the signal and close callback to stop remote work. Missing/restricted/loading/denied/unsupported/ rate-limited/ended/error states are explicit. No-JavaScript rendering is readable with connection controls disabled. Actual production stream transport and core/cloud resource integration remain separate work.

## Package manifest

Protocol fixture: `packages/contracts/component-fixtures/event-stream.json`.

| Field | Value |
| --- | --- |
| Name | @docsloth/event-stream |
| Version | 1.0.0 |
| Protocol | 1.x |
| License | Apache-2.0 |
| Runtime | react |
| Entry | dist/index.js |
| Recording policy | blocked |
| Fallback | html, markdown, json |
| Network hosts | none |
| Production write | no |
| Max runtime seconds | 120 |
| Integrity | all zeros (protocol fixture placeholder) |

| Tool | Effect | Confirmation | Input |
| --- | --- | --- | --- |
| subscribe | read | no | value |
| pause | read | no | value |

## Sources

| Source | Path |
| --- | --- |
| Component page | https://registry.docsloth.dev/components/event-stream.html |
| Markdown twin | https://registry.docsloth.dev/docs/event-stream.md |
| LLM index | https://registry.docsloth.dev/llms.txt |
| Specification | packages/contracts/component-specs/event-stream.md |
| Prop schema | packages/contracts/component-props/event-stream.schema.json |
| Protocol fixture | packages/contracts/component-fixtures/event-stream.json |
| Catalog | packages/contracts/component-catalog.json |