Repository navigation
docs: live demo will silently stop updating when the SSE wire change merges #548
Description
What
Merging the pre-chtypes stack will silently break the homepage live demo, because the docs site bundles the SDK from this repo while the demo streams from a separately deployed server.
docs/package.json:24—"@wavehouse/sdk": "workspace:*", so a docs build ships whatever SDK is in the tree.docs/src/components/LiveDemo.astrostreams fromhttps://iefrrvavd5akvphk7pq3.wavehouse.app.
Probed that backend directly:
$ curl -sN '.../v1/stream?table=gh_events'
: connected
No event: schema frame at connect — so it is still running the pre-stack server. The new SubscribeSchemaFrame sends one before the first row.
Why it breaks silently
This is exactly the skew the stack's own new warning describes (docs/src/content/docs/sdk/streaming.md, "Upgrade the SDK and the server together"). A new SDK against an old server never receives a schema frame, so _columns stays unset and _dispatch drops every row with a console.warn and no error callback.
liveQuery() makes it worse to notice: its backfill goes over REST and is unaffected, so the panel renders its initial snapshot, reports status live, and then simply never updates. Nothing turns red.
Options
- Sequence the deploys — upgrade the stats backend before or with the docs deploy.
- Pin the docs site to the last published SDK release (
"@wavehouse/sdk": "0.1.x"instead ofworkspace:*) until the backend catches up, then unpin. Also removes the general coupling where any unreleased SDK change can affect the marketing site. - Degrade gracefully in
LiveDemo.astro— surface "no data" when a stream reportslivebut delivers nothing for N seconds, so this class fails visibly rather than silently.
(2) is the smallest change and fixes the class, not just this instance; (3) is worth doing regardless.
Scope
Not a defect in the stack's code — it is a deployment-ordering consequence of the SSE wire change, and the stack documents the hazard for users. Found by the docs reviewer while reviewing the stack tip, which noticed the site was advertising a warning it was itself about to trip over.
Activity
EricAndrechek commentedon Sep 9, 2026
Fixed before the stack merged — recording it here since this is the original issue and it had no resolution note.
docs/package.jsonnow depends on"@wavehouse/sdk": "^0.1.1"from the registry instead ofworkspace:*(commit8277bf6e, shipped in #554). The caret takes0.1.xpatches and stops short of0.2.0, so merging a wire change can no longer push an unreleased SDK onto the landing page; moving the site onto the new wire is now a deliberate bump lined up with tagging the SDK release.tests/e2e/sdkdeliberately keepsworkspace:*.Verified rather than assumed at the time:
docs/node_modules/@wavehouse/sdkresolves to.pnpm/@wavehouse+sdk@0.1.1, whiletests/e2e/sdkstill symlinksclients/ts.make build-docsclean, so the published API still satisfiesLiveDemo.astro— only the wire changed in that stack, not the SDK surface.msg.data, which is what the deployed backend sends; the built docs bundle no longer contains theno-schemaguard.Two things that came out of it and are still live:
minimumReleaseAge(7 days), and the exclude list named only@wave-rf/*— the plugin scope.@wavehouse/*is now exempt too, otherwise a freshly tagged SDK would have been uninstallable by the docs site for a week after every release.patterns: ["*"], so once0.2.0publishes it would have proposed^0.1.1→^0.2.0in a routine Mondaydeps:PR.@wavehouse/sdkis now in thatignorelist (4c27c547), and the release runbook says so.The general version of this — that any SDK consumer upgrading ahead of their server hits the same silent stall, with no
errorcallback — is not fixed by pinning our own site. That is #577.(I filed #568 during the stack without searching first; it duplicates this. Closing that one and keeping this as canonical.)