@czap/web

Applies streamed HTML, state-driven re-renders, and LLM output to a live browser document without losing focus, scroll, or form state.

You usually don't install this directly — it arrives as a dependency of @czap/astro. Install that instead unless you are wiring DOM morphing, SSE streaming, or LLM chunk handling into a host that isn't Astro.

Install

pnpm add @czap/astro   # brings @czap/web with it
# direct use: pnpm add @czap/web effect@beta

For direct use, the main entry needs the Effect 4 beta peer — pnpm add effect@beta (a bare pnpm add effect installs 3.x and fails the peer check). The @czap/web/lite entry used below is Effect-free.

30 seconds

import { morphPure } from '@czap/web/lite';

const card = document.querySelector('#card')!;

// Diff #card's children against the new HTML. Matching nodes are
// kept in place rather than recreated.
morphPure(card, '<h2>Updated</h2><input name="q" />');

#card shows the new markup, and any element present both before and after the morph — the input, say — keeps its focus, value, and scroll position instead of being torn down and rebuilt.

Where it sits

The browser runtime layer: @czap/astro's client directives call into this package, and it depends only on @czap/core (shared state and runtime contracts) plus mediabunny for WebCodecs capture. The main entry adds the Effect-scoped surfaces: Morph with physical-state restore, SlotRegistry for addressing server-rendered slots in streamed HTML, an SSE client with reconnect and cross-tab resumption, and LLMAdapter for normalizing OpenAI / Anthropic / AI SDK chunk formats. @czap/web/lite is the pure subset of all that with no Effect dependency. Off-thread evaluation lives in @czap/worker, not here. See the package surfaces map for the full layout.

If it does nothing

Morph parses incoming HTML under a sanitized policy: <script> tags, on* attributes, and javascript: URLs in newHTML are stripped silently, by design. If markup you expected is missing after a morph, run it through sanitizeHTML (same entry) to see what survives.

Wire contract

czap:* CustomEvents

Single source: packages/web/src/wire/czap-events.ts. Dispatch through dispatchCzapEvent; subscribe through onCzap.

| Event | Role | | --- | --- | | czap:graph-state | Discrete graph-runtime state crossing on a bound element. | | czap:gpu-ready | GPU shader runtime initialized on the directive host. | | czap:llm-done | LLM stream finished; carries final accumulated text. | | czap:llm-error | Terminal server-side LLM stream error. | | czap:llm-frame | Structured UI frame emitted mid-stream. | | czap:llm-genui | Generated-UI tree rendered from the host catalog. | | czap:llm-start | LLM stream opened on the directive host. | | czap:llm-token | Incremental LLM text token. | | czap:llm-tool-end | Tool call completed. | | czap:llm-tool-start | Tool call started. | | czap:morph-rejected | Morph preserve constraint violated. | | czap:mutation | Graph mutation channel response after form submit. | | czap:reinit | Directive re-read after a view-transition swap (not final teardown). | | czap:request-snapshot | Recovery fetch requested after morph rejection. | | czap:satellite-state | Satellite boundary state crossing. | | czap:signal | SSE signal message payload from the stream directive. | | czap:slot-mounted | Slot registry registered a data-czap-slot element. | | czap:slot-unmounted | Slot registry removed a slot path. | | czap:state | Boundary state crossing (CSS/ARIA/uniform detail). | | czap:stream-connected | Stream SSE transport connected (includes post-reconnect). | | czap:stream-disconnected | Stream SSE transport lost; reconnect may follow. | | czap:stream-error | Stream transport or resumption failed. | | czap:stream-morph | Stream patch morph applied (one event per flushed patch). | | czap:teardown | Final directive teardown — release observers, do not re-init. | | czap:uniform-update | GPU/uniform consumers: live CSS/GLSL/WGSL values. | | czap:wasm-error | WASM kernel load failed. | | czap:wasm-ready | WASM kernels loaded onto window.__CZAP_WASM__. | | czap:worker-ready | Worker boundary runtime ready on the directive host. | | czap:worker-state | Worker boundary state crossing. |

Stream data-czap-* attributes

Single source: packages/web/src/wire/stream-attributes.ts. Read through streamWireAttr(key).

| Attribute | Role | | --- | --- | | data-czap-stream-url | SSE feed endpoint (required). | | data-czap-stream-artifact | Resumption artifact id for cross-tab replay. | | data-czap-stream-morph | Morph target: innerHTML (default) or outerHTML. | | data-czap-snapshot-url | Recovery snapshot endpoint (morph rejection / gap). | | data-czap-replay-url | Recovery replay endpoint (missed patch gap). |

Docs

• Getting started
• Hosting guide — CSP rules for SSE and LLM endpoints
• Glossary — the vocabulary used above
• API reference — generated from source

Part of LiteShip — powered by the CZAP engine (Content-Zoned Adaptive Projection), distributed as @czap/* packages.