@kolu/surface-app reference
The shell around a @kolu/surface app: the static, installable layer for apps
you run against your own server (kolu, drishti).
Surface is the live wire; surface-app is the shell served fresh around it.
Exports are grouped by subpath.
The listener
serveSurfaceApp serves the shell over HTTP and the surface over one WebSocket, from one call. The rest of this group is what it hands your app: the connection record, the event union, the upgrade-header allowlist, and the two constants both legs read.
| Export | Subpath | What it is |
|---|---|---|
serveSurfaceApp(opts) | /serve | The whole listener: shell, socket, gates, heartbeat, bind, teardown. |
SurfaceAppListenFailed | /serve | The one failure it reports, cause intact. |
SurfaceAppConnection | /serve | One accepted connection, and the handle that can end it. |
SurfaceAppEvent | /serve | The tagged union onEvent narrates. |
SurfaceAppHttpMiddleware | /serve | The shape middleware takes. |
reportSurfaceAppEvent(event) | /serve | The default narration policy, for an onEvent to delegate to. |
checkUpgradeHeaders(names) | /upgrade-headers (also re-exported from /serve) | The allowlist’s grammar, for an app that assembles its list. |
UpgradeHeadersSource<H> | /upgrade-headers (also re-exported from /serve) | How a listener obtains its list. |
pickUpgradeHeaders(request, names) | /upgrade-headers | The read half, for a hand-built listener. |
SURFACE_WS_PATH | . | /rpc/ws, the one path a surface speaks on. |
surfaceWsUrl(httpBaseUrl) | . | The dial URL from the http(s) base. |
thrownText(error) | . | An uncaught throw, printed for a bug report. |
The groups below are the pieces serveSurfaceApp composes. Reach for them directly when a listener needs something this call does not take: drishti dispatches per host on ?host=, picking which runtime serves a socket. kolu and this package’s example both ride the primitive.
serveSurfaceApp(opts)
serveSurfaceApp (@kolu/surface-app/serve) is the turnkey seam. It runs the shell over HTTP and the surface over one WebSocket, in one order: origin gate, upgrade, stale-tab check, heartbeat enrolment, serve.
const url = yield* serveSurfaceApp({
group: runtime.group, // snapshotted at the call — or `live: () => ({ group, handlers })`
handlers: runtime.handlers,
clientDist, // omit in dev — no bundle means no static route, never a fake one
manifest: { name: "my app" },
routes: myOwnRoutes, // merged alongside the shell — an MCP route, media, …
host,
port,
allowedOrigins,
tls, // present → an `https.Server`, and the returned URL says `https://`
middleware, // wraps every HTTP request — an app's bridge to its own logger
upgradeHeaders, // request headers this app reads off the upgrade, by name — or a thunk of them
services, // (connection) => Layer — what THIS connection's handlers require
});
- It owns the
http.Server, so theupgradeevent stays yours. - It mounts
surfaceAppLayeralongside your own routes, stands up thewsserver, binds, and registers its whole teardown on the enclosingScope. wsand@effect/platform-nodeare peer dependencies of the package. An app serving on Node already declares both, and a browser-only consumer of./solidnever pulls them in.- It returns the URL actually bound, so
port: 0reports the port the OS gave. - It fails with the typed
SurfaceAppListenFailed. - The surface runtime’s own lifetime is not owned here. Pass
{ group, handlers }and keepcloseanddoneat the composition root that built them. clientDistis optional, and its absence is the dev shape. No bundle means no static route at all, so an unmatched path 404s through the router.- The
manifestis still served without a bundle, because a dev proxy forwards/manifest.webmanifestto a server with no built client. The two mount independently.
The generation it serves
The generation is ServedGenerationSource. { group, handlers, expose? } is the generation written at the call, and { live: () => ({ group, handlers, expose? }) } is re-read at each accept, as a pair.
- A socket accepted after an
implementRootedSurfacesmount is indistinguishable from one accepted on a boot that already had that sibling. - A connection accepted before the roster moved keeps the generation it was built over until the client redials.
serveOverUnixSockettakes the same source.
expose
expose takes the same ExposeMap the MCP adapter takes and applies it to the websocket alone. A verb can then be reachable over a trusted unix socket and refused to browsers, without the app keeping a second write path beside the surface. Omit it and the socket serves the whole surface.
The shape, the refusal (SurfaceMemberNotExposed), the reserved members it can never gate, and the bind-time validation are all @kolu/surface/expose’s.
The inbound frame cap
serveSurfaceApp sets ws’s maxPayload to RPC_MAX_FRAME_BYTES, the framework’s published byte budget, and offers no option to move it. That is the budget exceedsFrameLimit publishes to senders. A transport cap that disagrees with it breaks the promise in one direction, or the wire in the other. See @kolu/surface/frame-limit.
Closing the scope
Closing the scope drains before it drops, in this order:
- New upgrades are refused.
- Every connection’s serving stack is closed and awaited. That is what releases its RPC fibers and every in-flight subscription it opened.
- The raw sockets are terminated.
- The listening socket is closed last.
When the finalizer resolves, nothing this listener started is still running.
- The listening socket closes last deliberately. Under Bun, closing the server while a socket is still open means its
closecallback never fires, so the finalizer never settles and aSIGINTed process never exits. - Node tolerates either order, so nothing upstream catches that.
- Refusing new upgrades is therefore the listener’s own job (a
drainingflag), not a side effect of closing early.
The upgrade’s headers — upgradeHeaders
A live wire is one websocket, so its one request is the upgrade. A header a reverse proxy stamps there (Tailscale-User-Login, X-Forwarded-For) is the only per-connection claim about who is calling that the wire can carry, and serveSurfaceApp owns the upgrade.
upgradeHeaders names which headers to keep. Each accepted connection carries those values on SurfaceAppConnection.headers, keyed by the spelling used here, and a services layer reads them per connection:
const url = yield* serveSurfaceApp({
// …
upgradeHeaders: ["Tailscale-User-Login"],
services: (connection) =>
Layer.succeed(Viewer)({
login: connection.headers["Tailscale-User-Login"],
peer: connection.remoteAddress,
}),
});
| Fact | Shape | Notes |
|---|---|---|
upgradeHeaders | UpgradeHeadersSource<H> — ReadonlyArray<H> | () => ReadonlyArray<H> | The allowlist, empty by default. An array is read once at the bind; a thunk is re-read at each accept |
connection.headers | Readonly<Partial<Record<H, string>>> | The named headers this upgrade carried. Matched case-insensitively against the wire, keyed by the spelling in upgradeHeaders |
connection.remoteAddress | string | undefined | The direct TCP peer, which is the proxy itself when there is one. Never a guess |
services | (connection: SurfaceAppConnection<H>) => Layer.Layer<Svc> | The per-connection Layer those facts are read into |
- A header nobody named is not available at all.
- Effect’s socket-server protocol forwards no per-request context, so a connection-scoped fact is provided through
services, never carried on the request. His inferred fromupgradeHeaders, soconnection.headers["X-Forwarded-For"]does not compile when the allowlist said"x-forwarded-for". An open index would hand a misspelling the sameundefineda real absence has.- A named header the request did not carry is absent from the record, so
undefined(“not sent”) and""(“sent empty”) stay different facts. - A repeated header arrives folded into one comma-joined string, with the separator node itself uses (
", "). It is a string, never an array. This seam reports that string; it does not join. set-cookieis refused at the allowlist rather than folded into a string nothing could split back apart (RFC 6265 §5.2). It is node’s one array-shaped exception, and the one header whose values carry commas of their own. An array reaching this seam is that same defect, and is refused rather than joined.
What the allowlist refuses
The allowlist is the access, not a filter over a header bag a services layer could still reach. Cookie and Authorization are not on the connection at all. Naming a header is the app saying it trusts the proxy that writes it, and that is a claim only the app can make.
Two things are a defect:
- A name outside HTTP’s field-name grammar (node’s own
validateHeaderName). - One wire header named twice (
X-Forwarded-Forbesidex-forwarded-for), which would file one value under two keys.
For a fixed array, the effect raises the defect when it runs, before anything binds, so no listener is left behind. It is deliberately not a SurfaceAppListenFailed, which a port-retry policy would loop on forever against something no port can fix.
Who may write a named header
This seam reports; it does not authenticate. What reaches connection.headers is whatever was on the upgrade, and a client dialling the listener directly can send Tailscale-User-Login itself, which services then receives as faithfully as a proxy’s own.
- Naming a header is sound only when the proxy owns it: it strips or overwrites any inbound copy, and is the only way in (the listener bound to loopback or a tailnet).
- Naming one the proxy merely passes through hands every caller a claim they wrote about themselves.
- Nothing here can check that, because the deployment is not visible from the listener. That is why the naming is the app’s to do.
- kolu’s
x-forwarded-foris safe becauseviewerAddressOfweighs the claim against the direct peer. An app that names an identity header gets the value, never that judgment.
A live allowlist, read at each accept
The list itself can move while the listener is up. An app whose identity part is switched on at runtime does not know its headers at the bind. Pass a thunk and the next accept reads the list that is live then, so a socket accepted after the switch is indistinguishable from one accepted on a boot that already had it. That is the same confluence claim ServedGenerationSource makes for the served set.
// re-read at each accept; annotated so `H` stays a literal union
upgradeHeaders: (): ReadonlyArray<"Tailscale-User-Login"> => identity().headers,
- The two arms are told apart by
typeof. An array is never callable, so there is nothing here to mistake for a thunk, and no wrapper is needed. Hinfers from either arm, and on either it is only as narrow as the list’s element type.- A
ReadonlyArray<string>(a widely typed variable as much as a thunk returning one) widensHtostring, and every header read compiles again. A literal array, anas const, or the return annotation above is what keeps the guarantee.
A live list that refuses itself
A bad name in a live list belongs to whatever part offered it, and one part’s defect must not reach the wire’s other tenants. So the socket is accepted and served with no named headers. Every request on it reads as nobody, which is the state an app already defines for “no identity”, and the fault is reported as UpgradeHeadersRefused.
- The fault is reported at each accept that reads a bad list, for as long as the offering part keeps minting one. Each of those accepts really did serve an anonymous connection.
- A thunk that simply throws takes the identical path, and the event’s
errorsays which happened. - Terminating the socket would let one part’s list take every connection down with it, and throwing would take the process.
- Call
checkUpgradeHeaders(names)(@kolu/surface-app/upgrade-headers) where you mint the list, so the offending part fails there, with the same sentence, before any socket is accepted. - A fixed array is the other arm: a name it cannot carry takes the bind down, because that array is the app’s composition root and there is nothing else to blame.
SurfaceAppConnection
One accepted connection: { id, url, remoteAddress, headers, close }. It is what a per-connection services layer is built from, and the handle that can end the connection.
ConnectedandDisconnectedcarry the sameSurfaceAppConnectionobject, so a consumer can pair them by identity.idis a listener-scoped ordinal, which is what a log line wants (kolu’s per-connectionws:field).servicesstays a separate option fromonEvent: it returns aLayer, which is a different kind of thing from narration.
connection.close(code?, reason?)
services is also where the app decides a connection must go: a session that logged out, expired, or was revoked. Open the lease inside the layer, so the layer’s release is what closes it:
services: (connection) =>
Layer.effect(Session)(
Effect.acquireRelease(
Effect.sync(() => {
const lease = sessions.lease(connection.headers["Tailscale-User-Login"]);
// Logout, expiry, revocation: the lease ending ends THIS connection now.
lease.onEnd(() => connection.close(4401, "session ended"));
return lease;
}),
(lease) => Effect.sync(() => lease.close()),
),
),
connection.close(code?, reason?) stops serving this socket, releases everything the serve owns (the RPC fibers, every in-flight subscription, the per-connection services layer), and closes the peer with your frame. SurfaceSocketServing.close takes the frame, so the listener’s drain (close()) and the app (close(code, reason)) spell close the same way.
| Fact | Shape | Notes |
|---|---|---|
connection.close | (code?: number, reason?: string) => void | Ends this connection. The closure that built the record bound it to its own serving, so there is no id to look up and one connection cannot close another |
code | 1000 or 3000–4999 | 1000 (normal closure) is the default, because a caller who passed none made no policy claim. A policy end names its own: 4401 is the application-range code for “session ended” (RFC 6455 §7.4.2) |
reason | at most 123 UTF-8 bytes | The control-frame payload is 125 bytes, less the two-byte code. Counted in bytes, so 42 of あ is already over |
| a bad frame | throws RangeError at your call | Checked before anything changes: the connection stays open, services keeps running, and a later valid close still works |
| idempotence | — | The first call owns the frame. A second is a no-op, and so is a call after the peer has already hung up |
ws’s own validation cannot be the gate, because it runs after putting the socket inCLOSING, which strands the peer with no frame and no timer.- Calling it from
servicesitself, or from aConnectedhandler, is safe. The record is built before the serving exists (the serving is built overservices(connection)), socloseresolves its serving lazily. - The accept site then closes the peer the moment the serving is there. A close from
servicesstill builds that layer and releases it at once. - A close from
Connectedmeansservicesis never called, because no handler could run on the connection anyway. Disconnectedreports once, and reports what the transport saw: normally the code you passed, because a conforming peer echoes the close frame.- It is
1006when the peer never answered andws’s close timeout dropped it. A peer that answers nothing is exactly what a credential cut can face, so the frame is a request, not a promise.
Closing and the heartbeat
Refusing the heartbeat is not a cut: a refused probe counts as alive (@kolu/surface/heartbeat), so only an unanswered one trips the client’s watchdog, after interval + timeout (25 s at the defaults).
A client with no watchdog (a stdio MCP bridge, a raw socket) never closes. A credential decision must not wait on a liveness heuristic.
SurfaceAppEvent
Observation is one option, onEvent, taking one tagged union, because every consumer has exactly one logger.
_tag | Carries | Default (reportSurfaceAppEvent) |
|---|---|---|
Connected | connection | silent — the accept a live-connection count increments on |
Disconnected | connection, code, reason | silent — the same connection hung up (peer, reaper, or the app’s own connection.close), with the close frame’s own account of why |
SocketError | error, url | loud console.error — a transport error |
GenerationRefused | error, url | loud console.error — a live generation restrictHandlers refused. The socket is terminated |
UpgradeHeadersRefused | error, url | loud console.error — a live upgradeHeaders could not be produced. The socket is served anyway, with no named headers (why) |
StaleTab | claimedPid, url | silent — a server that restarted while a tab was open is ordinary, not a fault |
DisallowedOrigin | origin, url | loud console.warn — a blocked hijack, which a shared gate must never drop in silence |
ServingFailed | cause, connection | loud console.error — done must be observed |
- A refused generation terminates the socket: there is no honest reduced thing to serve when the served set itself is unservable.
ConnectedandDisconnectedare the pair a live-connection count is built from. The package’s own example counts itsserverStats.connectionson them.
reportSurfaceAppEvent(event)
The default narration policy, exported so an onEvent of your own can delegate to it. The table above is what it prints.
SurfaceAppListenFailed
The one failure serveSurfaceApp reports. It carries the cause verbatim, so a consumer’s port policy reads cause.code === "EADDRINUSE" rather than matching a message string.
SurfaceAppHttpMiddleware
The shape middleware takes. It wraps every HTTP request, which is an app’s bridge to its own logger. Error and response types are preserved, and it adds only HttpServerRequest.
checkUpgradeHeaders(names)
The allowlist’s grammar, for an app that assembles its list. It returns the names unchanged, and throws on a bad one, so the refusal lands where the list is minted rather than at the accept. It is exported from /upgrade-headers and re-exported from /serve.
UpgradeHeadersSource<H>
How a listener obtains its list: ReadonlyArray<H> (the app’s composition root, checked at the bind) or () => ReadonlyArray<H> (live, read at each accept).
pickUpgradeHeaders(request, names)
The read half, for a hand-built listener holding its own IncomingMessage: the named headers that upgrade carried, and nothing else.
- Case-insensitive, keyed by the spelling in
names, absent when not sent, prototype-free and frozen. - Re-rolling it by hand is how a listener grows back the
constructorand__proto__and array-value hazards this closes. - A hand-built listener on
acceptSurfaceSocketstands in its ownupgradehandler holding the request, so it reads what it needs directly.upgradeHeadershas nothing to offer it, the same split asexpose.
SURFACE_WS_PATH
/rpc/ws, the one path a surface speaks on. Both legs import this constant, so the dial URL and the upgrade handler cannot drift. Any other upgrade target is destroyed.
surfaceWsUrl(httpBaseUrl)
The dial URL from the http(s) base: the one https: to wss: swap, and browser-safe.
thrownText(error)
An uncaught throw, printed for a bug report. It normalizes a Safari, V8 or DOMException throw, is framework-free, and never returns the empty string. The fault boundary is what calls it.
Serving the fresh shell
These are HttpRouter layers (effect/http), not framework installers: merge them into your app layer in any order. Routes are ranked by specificity, so your /rpc/* route always beats the static GET /* catch-all.
| Export | Subpath | What it is |
|---|---|---|
surfaceAppLayer(opts) | /server | The no-store shell, immutable assets and optional manifest, in one layer. |
SurfaceAppLayerOptions | /server | That layer’s options. |
freshStaticLayer(opts) | /server | Fresh static files, and an optional notification worker. |
pwaManifestLayer(manifest, path?) | /server | The web manifest. |
surfaceAppLayer(opts)
surfaceAppLayer (@kolu/surface-app/server) serves the shell: a no-store index.html that names a content-hashed bundle, immutable /assets/*, a 404-on-miss for a stale hash, an SPA fallback, /sw.js, and the web manifest.
const app = Layer.mergeAll(
rpcRoutes,
surfaceAppLayer({ clientDist, manifest: { name: "my app" } }),
);
const server = createServer();
server.on(
"request",
await Effect.runPromise(
Effect.gen(function* () {
const httpEffect = yield* HttpRouter.toHttpEffect(app);
return yield* NodeHttpServer.makeHandler(httpEffect, { scope });
}).pipe(Scope.provide(scope), Effect.provide(NodeHttpServer.layerHttpServices)),
),
);
- Staleness is structurally impossible, because the one document that names the bundle is always re-fetched.
- It requires the platform services that read files (
FileSystem,Path,HttpPlatform), which on Node come fromNodeHttpServer.layerHttpServices. - It throws at composition time if
assetPrefixis malformed, or would capture a shell path. That would put a compressedindex.htmlsibling on the wire (kolu#1319).
Own the http.Server
NodeHttpServer.makeHandler on a server you created keeps the upgrade event yours. HttpServer.serve registers its own upgrade listener, and Node fans an event out to every listener, so it would also answer a socket acceptSurfaceSocket has already upgraded.
No 304s
The static layer strips If-None-Match and If-Modified-Since before the file engine sees them, so every hit is a full 200. The platform’s validator is size and mtime, and in a Nix store every mtime is the epoch, where a 304 could replay a stale same-size shell.
The build commit
The build commit is injected as window.__SURFACE_APP_COMMIT__ onto the no-store shell by the surfaceApp() plugin, never a bundler define. A define bakes the sha into a content-hashed, immutable asset and strands returning browsers. No app writes a sha.
SurfaceAppLayerOptions
That layer’s options: an optional clientDist, manifest and serviceWorker, and the freshness paths. ServeSurfaceAppOptions extends it, so the shell half is named once.
freshStaticLayer(opts)
freshStaticLayer serves fresh static files, plus the optional notification worker. Like surfaceAppLayer, it requires FileSystem, Path and HttpPlatform, and throws at composition time on a malformed assetPrefix or one that would capture a shell path.
A DEEP LINK IS ANSWERED WITH THE SHELL AT THE ADDRESS ASKED — never a redirect. The layer builds the file engine with no directory index and serves the shell as the one file it is (index.html), so an address naming a directory is never answered with a 301 to that address plus a slash.
Effect 4.1’s engine redirects a directory request. Serving the shell as the directory / therefore bounced every deep link: /notes/today came back as /notes/today/, an address that names neither a file nor a page, and a client draws nothing.
pwaManifestLayer(manifest, path?)
The web manifest, as its own layer. path? is where it is served.
Building the client dist
buildSurfaceClient(opts) (@kolu/surface-app/bun) is the Bun-runtime build. It produces the dist the static layer above is built to serve, and nothing about that dist is the app’s to remember.
| Export | Subpath | What it is |
|---|---|---|
surfaceApp() | /vite | Vite plugin that injects the build commit onto the shell. |
buildSurfaceClient(opts) | /bun | The Bun build: hashed assets, rewritten shell, siblings, splitting. |
SurfaceClientBuildOptions | /bun | Its options. |
SurfaceClientBuildResult | /bun | Every hashed URL the shell now names, plus a report per asset. |
AssetReport | /bun | One asset’s identity size and its siblings’ sizes. |
injectShellHead(html, { preloadHrefs, commit }) | . | The whole head prelude in one splice. |
injectShellCommit(html, commit) | . | That same splice with nothing to preload. |
PRECOMPRESSED_ENCODINGS | . | The [encoding, suffix] table both halves read. |
assertAssetPrefix(assetPrefix?) | . | A hashed-asset request prefix, checked and handed back. |
assetDirOf(assetPrefix?) | . | The dist-relative directory that prefix names. |
HASHED_NAMING | . | The naming template every hashed output is emitted under. |
chunkPattern(module, ext?) | . | What the split chunk for a module is called. |
chunkUrlPattern(module, assetPrefix?, ext?) | . | That same rule as a request under the hashed prefix. |
surfaceApp()
The Vite plugin, on /vite. It injects the build commit onto the shell.
buildSurfaceClient(opts)
The Bun build. One call writes:
- content-hashed
/assets/*: the entry, the split chunks and the extra assets; - the
no-storeshell, rewritten to name them; - the commit, injected onto that shell;
- a
<link rel="modulepreload">for each chunk the entry statically imports; - the precompressed siblings.
const { jsHref, assets } = await buildSurfaceClient({
entrypoint: resolve(clientDir, "main.tsx"),
distDir,
htmlTemplate: resolve(clientDir, "index.html"),
entryHtmlPlaceholder: `src="./main.tsx"`,
plugins: [solidJsx],
});
for (const a of assets) console.log(a.file, a.bytes, a.siblings);
Siblings and splitting
There is no precompress flag and no splitting flag.
- A sibling is written only when it beat identity, only under the prefix the layer negotiates, and never for a type the layer refuses. A flag would only choose between the negotiation working and it having nothing to serve.
- Splitting is what a dynamic
import()in your own source already asked for.splitting: falseinlines that chunk, which is deferred in evaluation and identical on the wire. - With one entrypoint and no dynamic import the output is unchanged.
Preloading the entry’s static chunks
Splitting hands the entry a chunk it imports at the top: the module the bundler hoisted out because the entry and a deferred chunk both need it. A browser handed only the entry’s URL cannot ask for that file until it has fetched and parsed the entry, so the split costs one extra round trip on first paint.
- The build reads its own chunk graph (
Bun.build({ metafile: true })) and names those files in the shell, transitively, so the fetches start while the HTML is still parsing. - A
dynamic-importchunk is never preloaded. That would fetch on first paint exactly whatimport()was written to defer. - An entry that split into nothing gets no tags at all.
- A static import that is not a JS module is refused, loudly. The bundler emitted a file this build rewrites no placeholder for, so the shell would name it nowhere.
The hashed dir
Every rebuild prunes the hashed dir (<distDir>/assets/ by default) down to what it just produced, plus their sourcemaps and siblings.
- A hashed file the new shell does not name is unreachable, and leaving it there is what makes a long dev session pay brotli over a growing pile.
- A sibling that already sits beside an unchanged asset is never recompressed: same name means same bytes.
- Your app’s stable-URL files (icons, fonts, a manifest) belong in
publicDir, which lands at the dist root and is never touched.
SurfaceClientBuildOptions
The build’s options: the entrypoint, distDir, the HTML template and its placeholders, extraAssets, publicDir, minify, commit and assetPrefix.
assetPrefix
assetPrefix (default /assets/) is the one thing about the dist’s shape you may say, and the right answer is not universal: it is a fact about whose URL space sits at /.
- An app serving somebody else’s files at
/cannot leave the bundle on the convention. olai serves a person’s own directory, so/assets/notes.mdis one of their pages. A miss under the immutable prefix 404s by design rather than reaching the shell, so a whole folder of theirs would have no page at all. - Pass the same string to the build and to
freshStaticLayer, and the collision is gone.assetDirOfderives the dist-relative directory from it, so the hrefs in the shell and the bytes on disk are one setting rather than two that can part. - The prefix must start and end with
/, and must not be the root. Each refusal throws where it is written. - Vite-built clients say the same thing through Vite’s own
build.assetsDir. - Moving the prefix wants a clean
distDir. The prune measures the directory this build wrote and cannot know where the last one put its files, so a rebuild that moves the prefix leaves the vacated directory behind.
SurfaceClientBuildResult
{ jsHref, assetHrefs, assetPrefix, preloadHrefs, assets }: every hashed URL the shell now names, plus a report per asset.
- The URLs are the JS entry, one per extra asset, and the entry’s static chunks in load order.
assetscarries anAssetReportper compressible asset in the hashed dir. Sourcemaps and already-compressed media are skipped, and absent from the report.
AssetReport
{ file, bytes, siblings }: the identity size and each sibling’s size, keyed by Content-Encoding.
injectShellHead(html, { preloadHrefs, commit })
The whole head prelude in one splice, for a caller templating its own shell from a build result. Preload links come first, then the build identity.
injectShellCommit(html, commit)
That same splice with nothing to preload: the build identity alone.
PRECOMPRESSED_ENCODINGS
The [encoding, suffix] table both halves read: freshStaticLayer to negotiate, the builder to emit.
assertAssetPrefix(assetPrefix?)
A hashed-asset request prefix, checked and handed back. It is the one place its shape is judged, so a prefix the build refuses is not one the server accepts.
assetDirOf(assetPrefix?)
The dist-relative directory that prefix names, which the Bun build reads to choose its outdir.
HASHED_NAMING
The naming template every hashed output is emitted under ([name]-[hash].[ext]). /bun hands it to Bun.build’s naming for entry, chunk and asset alike, so the rule is spelled once.
chunkPattern(module, ext?)
That template read backwards: what the split chunk for module is called, anchored to the whole filename, for a caller that must name the file before the build has run.
- It is built from
HASHED_NAMINGrather than re-spelled, so the two directions cannot drift. extdefaults tojs; pass"css"to name a hashed stylesheet.- It is a RegExp, because callers hand it to a route matcher and print it in a diagnosis.
chunkUrlPattern(module, assetPrefix?, ext?)
The same rule as a request under the hashed prefix. The filename half is chunkPattern’s, not a second spelling of it, and it is taken through assertAssetPrefix so a prefix the build refuses is not one a matcher accepts.
Accepting a browser socket
These are the pieces a hand-built listener assembles when serveSurfaceApp does not fit: the accept, the serve, the stale gate and the reaper.
| Export | Subpath | What it is |
|---|---|---|
acceptSurfaceSocket | /server | Accept, reap and sequence, in one call. |
serveSurfaceSocket | /server | Serve { group, handlers } over one accepted socket. |
SurfaceSocketServing | /server | The handle serveSurfaceSocket returns. |
gateStaleSocket | /server | The WS-upgrade handshake gate. |
startWsHeartbeat · heartbeatSweep | /server | The server-side liveness reaper, and its one sweep. |
STALE_PROCESS_CLOSE_CODE · SERVER_PROCESS_ID_PARAM | /server | The stale-tab vocabulary the two sides share. |
acceptSurfaceSocket
acceptSurfaceSocket (@kolu/surface-app/server) accepts a browser WebSocket onto a served surface. It owns the server-side liveness reaper and sequences stale-gate, enrol and serve in one accept(...), so a socket can never be served un-enrolled. It is the server twin of the client’s connectSurface watchdog.
serveSurfaceSocket
serveSurfaceSocket({ group, handlers, socket, services? }) is the serve half: the browser-facing counterpart of serveOverStdio and serveOverUnixSocket. It takes the same { group, handlers } pair implementSurface returns, and replaces the oRPC RPCHandler(...).upgrade(ws) call.
servicesis aLayersupplying whatever this one connection’s handlers require.- It is the seam a per-viewer fact rides: kolu’s
viewerAddressandforwardedFor, taken off the upgrade request’s own socket and headers. - Effect’s socket-server protocol has no per-request header channel, which is why the fact arrives as a layer.
SurfaceSocketServing
The handle serveSurfaceSocket returns: close(code?, reason?) and done.
closeis the one close, whether the listener’s drain or the app calls it, and the frame is validated first.doneis the fault channel to observe.
gateStaleSocket
The WS-upgrade handshake gate (error-handler-first; close 4001). It takes no live id: it compares the echoed pid against this process’s surfaceProcessId() (@kolu/surface/identity). That is the same value the reserved system/identity member answers with, so the two sides cannot be pointed at different strings.
startWsHeartbeat · heartbeatSweep
The server-side liveness reaper, and its one sweep.
STALE_PROCESS_CLOSE_CODE · SERVER_PROCESS_ID_PARAM
The stale-tab vocabulary the gate and the client’s close classifier share.
Connecting from the client
connectSurface and connectSurfaces (@kolu/surface-app/solid) are the turnkey single- and multi-surface seams. Each builds a socket, a websocketLink, the surfaceClient(s), and a default-on liveness heartbeat in one call.
| Export | Subpath | What it is |
|---|---|---|
connectSurface(opts) | /solid | The single-surface seam. |
connectSurfaces(opts) | /solid | The multi-surface seam: siblings, an optional root, and a roster move. |
conn.redial(surfaces) | /solid | Takes a new sibling roster in place. |
conn.connectionEpoch | /solid | How many usable connections this wire has established. |
createProcessIdEcho() | /connect | One pid echo, for an app that shares it across wires. |
createServerLifecycle({ wire, probe }) | /solid | The connection lifecycle, from the wire’s status and a processId probe. |
createLiveSignal | /solid | The watchdog-backed LiveSignalHandle a websocket client requires. |
The heartbeat probes the framework-reserved system/live tag (@kolu/surface/liveness) over the very dispatch it guards, so no app supplies a probe, or forgets one.
connectSurface(opts)
The single-surface seam. It returns { link, client, readout, dispose }.
- It is async: the dial is
websocketLink, and building a protocol and its fibers is an effect. - It takes the surface, never a separate group. The wire is built from
surface.groupright here, so a client and a wire that disagree about which members exist is unspellable. urlis optional. Omitted, it defaults tosurfaceWsUrl(location.origin), the page’s own origin through the one scheme-swap and path derivation. A browser app dials the origin that served it.- Omitting
urlwith nolocationin scope (a Node caller) throws loudly, before anything is dialled. Pass the URL you actually mean there. - It carries no
connectionEpochand needs none. With no generations, itslink.wire.onStatusopen edges are the establishments, undeduplicated.
connectSurfaces(opts)
The multi-surface seam. It takes the sibling map and an optional root, and is async, heartbeated and url-defaulting exactly as connectSurface is.
- The wire is built from
composeSurfaceContractsright here, so the same claim holds for a bundle. - A call that passes nothing (no root and no siblings) is refused. Such a wire carries no member at all, and there is no reserved tag for the watchdog to probe.
// ASYNC: the dial is an effect. `link` is the `{ dispatch, wire, dispose }` the
// websocket link minted; `dispose()` releases its scope (dial/ping/response
// fibers) as well as stopping the watchdog.
const { link, client, readout, dispose } = await connectSurface({
surface,
url,
// REQUIRED: what happens when the server retires this wire (a tab bound to a
// process that is gone — the link will never dial again). No default, so a
// connection that compiles has an answer. `reloadForUpdate` is the one-liner;
// pass your own handler to take the screen instead.
retired: reloadForUpdate,
});
What the connection carries
connectSurface returns { link, client, readout, dispose }; connectSurfaces returns { link, clients, core, transport, connectionEpoch, readout, health, redial, dispose }.
| Member | Meaning |
|---|---|
link | The WebsocketLink — { dispatch, wire, dispose, diagnostics }. Read link.wire for the status stream and forceReconnect |
client / clients | The reactive surface client, or one scoped client per sibling. clients is one object for the connection’s life, and a redial mutates it in place |
core | (multi only) The root surface’s own client when core was passed, and typed undefined when it was not, so a siblings-only caller reads no optional it has to check |
transport | (multi only) The branded LiveSignalHandle. Pass it whole to connectSurfaceMap(map, conn.transport) |
connectionEpoch | (multi only) How many usable connections this wire has established, as a Solid accessor, so a createResource can key on it. See below |
readout | The readout: the wire’s own four states folded with the subscription-health fact into the five an indicator may report, memoized |
health | (multi only) The client bundle’s own fact over every sibling, and the root under its name. It is live when their subs and the shared transport leg all are |
redial | (multi only) Async: take a new sibling roster in place. See above |
dispose | Async: stop the heartbeat, tear down standing subscriptions, release the link’s scope |
- On the multi seam
linkis the standing wire:dispatchandwireare the same values across aredial, so a consumer may hold them.diagnosticsis the one leg that belongs to a generation, and reads through to whichever is current. link.dispose()isconn.dispose(). The wire is the connection’s resource and its state gates it, so there is no second, ungated door onto the same release.link.wireis a watchable wire, not a socket object such as aws: PartySocket.coreneeds no tag-scoping wrapper: the root’s tags are already the bare ones the combined dispatch carries.connectSurfaceMap(map, conn.transport)slices the sibling bymap.nameafter the guard, so the map inherits this wire’s watchdoglive.transportis stable across aredial, so a map built over it keeps working.healthis reactive about the roster too, so a memo bound to it re-folds when a sibling arrives or leaves.redialis idempotent: a roster already carried dials nothing. It returns this same connection, retyped.
extraGroups
Tags that ride the same wire but are not sibling surfaces go in connectSurfaces’ extraGroups: a keyed map’s group (for connectSurfaceMap(map, conn.transport)), and a host’s hand-written root procedures (reached through conn.transport.dispatch).
- The wire’s
RpcGroupcarries every tag’s payload and success schemas, and Effect RPC’s flat client resolves a call by looking its tag up there. A tag the group never minted cannot be dispatched at all. - Each entry must be disjoint from the root, from the composed siblings and from every other entry.
- The merge is
mergeDisjointGroups(@kolu/surface/define), which claims every half’s tags before merging, and throws naming the tag and the two halves that claimed it. - It names each sibling by key (
surfaces.<key>), never the composed bundle as one half, so a collision report says which sibling. - An entry goes in as it is. The option takes an open element union, because
RpcGroupis invariant in that union, and a precisely-typed group is not assignable to the erasedRpcGroup<Rpc.Any>even though every element is one. - The seam takes that erasure on itself, the same law
mergeDisjointGroupsadopted, so no caller writes a double cast at the door onto a safety proof.
The rooted bundle
A composed wire may also carry an unprefixed root surface, through connectSurfaces’ core: { surface, name } slot. The siblings are tagged surface/<key>/<member>/<verb>; the root keeps the bare surface/<member>/<verb> a standalone surface has.
With a core present:
- its members join the one dialled group, through the same counted merge
extraGroupsrides; - it gets its own typed
surfaceClient, returned asconn.core; - it joins the health fold, and therefore the readout, under
name, so a stopped root subscription is named (<name>/<sub>) exactly like a sibling’s; - both reserved round-trips address the root’s bare tags:
surface/system/identityfor the echo, andsurface/system/livefor the watchdog.
const conn = await connectSurfaces({
surfaces: enabledPlugins, // may be {} — a root-only wire is ordinary
core: { surface: coreSurface, name: "olai" },
retired: reloadForUpdate, // url defaults to this page's origin
});
conn.core.cells.plugins.use(); // the root's own typed client
conn.clients.kolu.cells.terminals.use();
- That probe path is the one
createSurfaceSocketandcreateLiveSignalalready implement, by omittingsiblingKey. The root is on every serve this wire can reach, so it is the one probe target a wire whose sibling set varies per serve can trust. surfacesmay be empty: a wire that carries only its root is an ordinary wire.- Omit
coreand every one of those sentences reverts: the probes address the first sibling’s tags, andconn.coreisundefined. - Whether a wire has a root is a call-site fact, not a runtime one. The seam is two overloads, so
core: enabled ? { … } : undefinedis a type error rather than aconn.corethat types as a definite client and isundefinedat runtime. - A caller who genuinely wants both shapes branches the call: the two hand back different types.
- It is a slot on the existing seam rather than a second constructor, because a root is data about one wire, not a second kind of wire.
Refusals at the seam
Three miswirings are refused, all of the quiet kind:
- A
core.surfacethat is a sibling-scoped surface. The client face mints standalone tags whatever prefix the value carries, so such a wire would connect and then answer nothing.exposeRootedFacesstates the same law on the serve side. - A
core.namethat is also a sibling key. The health fold is keyed by that word, so one of the two clients would vanish from it in silence. - A
core.namethat is empty or carries a/.
core.name is a label and not a tag segment: the root’s members keep their bare tags, so the word never reaches the wire and is held to no tag grammar. It is the word a degraded readout says, prefixed onto every stopped subscription as <name>/<sub>. A readout that cannot say it (/sub, or a word indistinguishable from a sibling path) is refused at the door.
conn.redial(surfaces)
Takes a new sibling roster in place. A new wire is dialled, and that part is not negotiable.
- Effect RPC resolves a call’s payload, success and error schemas by looking its tag up in the
RpcGroupits client was built over, and that group is fixed at the dial.openWireLinkdoesRpcClient.make(group, …)once, over a protocol whose fibers live in the link’s own scope. - A sibling that joins the roster brings tags that group never minted, so no client built before it can dispatch them.
- The far end has the same constraint, because each accepted socket builds its own
RpcServerover the generation it was handed at accept. - Only the wire is replaced. The connection itself, and every handle you hold off it, stays.
const conn = await connectSurfaces({
surfaces: {},
core: { surface: core, name: "olai" },
retired: reloadForUpdate, // …and the rest, as above
});
// …the served roster moved. Same connection, new wire underneath:
await conn.redial({ kolu: koluSurface });
conn.clients.kolu.cells.terminals.use(); // the arrival is on the map you hold
The clients map
clientsis the same map, mutated. An arriving sibling appears on it, and a departing one is dropped.- A departed client, which a still-mounted component may hold, refuses in words on its next call rather than dialling tags this generation does not serve.
- A key whose
Surfacevalue was replaced (an edited plugin rebuilt at a new chunk) counts as a departure and an arrival. Its client is rebuilt, because one built over the old spec binds members the new one may not have. - Mutating in place is what keeps the identity, and the price is that the map is not reactive.
- Bind
conn.healthorconn.readoutfor anything that must follow the roster, and read the map itself for the clients, after theredialresolves. Both read the bundle’s own roster accessor (see Consuming in SolidJS).
What keeps its identity
core,transport,link,readoutandhealthkeep their identity, so a consumer holdingconn.link.wireorconn.transportat module scope keeps holding something live. drishti holds exactly those, forcreateServerLifecycleandconnectSurfaceMap.readoutnever readsretiredfor a roster move: a move is not a retirement.
Standing subscriptions
- Standing subscriptions re-open themselves. The wire underneath is a
followingWire, whose supersession fails what was in flight with the transport error the per-subscription retry fence already retries on. - The next frame each subscription sees is its fresh snapshot from the new generation. No app code re-subscribes, and there is no second recovery path beside the fence.
- It is not instantaneous. The fence waits one retry interval (
STREAM_RETRY_DELAY_MS, 1 s, a schedule sized for a flapping socket), so every standing subscription readspendingacross a roster move and its first fresh frame lands about a second later.
When a redial dials nothing
- A roster this connection is already on dials nothing. “Already on” is the client bundle’s own comparison: every key present with the same
Surfacevalue, which is the same test that decides who survives a move. - The documented pattern is to publish the roster as a cell and drive
redialoff its changes, where a redundant call is ordinary. Dialling anyway would fail every call in flight and re-open every standing subscription on the page. - Refusals still come first: a no-op roster that is also illegal is still refused.
Options and order
redial re-uses every option this connection was dialled with: the url (thunk included), the heartbeat tuning, extraGroups, onClientError and the socket options. A consumer cannot drift them by re-spelling the call.
- It owns the order. Every refusal the new roster earns is raised before anything is dialled, the replacement wire is dialled before the old one is given up, and the handover (adopt the wire, move the clients, re-fold the health) is synchronous.
- A dial that throws costs you nothing: the connection is untouched and still on its current roster.
- “Resolved” is the seam’s own await, not an open socket.
connectSurfaceshands back a connection whose wire may still be connecting, exactly as a first dial does. - A
dispose()that lands while the dial is in flight is terminal and wins. The replacement wire is released and the redial rejects, rather than adopting a wire onto a connection the caller has already given up. - A redial while another is in flight is refused, because this connection dials one wire at a time. A queue belongs to the caller that has two rosters in hand. A redial after
disposeis refused too. - The returned value is this same connection, retyped to the roster it now carries. A binding still typed on the old roster keeps claiming departed keys exist, so re-bind through the result:
conn = await conn.redial(next).
The root does not move
Only the siblings are re-rostered. The root is the member on every serve this wire can reach, which is what makes it the reserved probes’ target on a bundle whose sibling set varies.
- A
corethat could change would make this a secondconnectSurfaces. Dial a different root by callingconnectSurfacesagain. - On a rootless wire the probes address the first sibling, and “first” moves with the roster, so the watchdog re-reads its target per probe rather than resolving it at the dial.
conn.connectionEpoch
Following the roster in place hides almost everything: a standing subscription heals itself onto the new wire, and readout reads live throughout, because the page never stopped being connected.
That is right for anything computed over the connection, and wrong for anything computed from it. A viewer identity resolved from the WebSocket upgrade’s headers is the case: it is stale the instant a different socket carries the calls, and nothing else on the connection will mention it.
conn.connectionEpoch is that fact, as a Solid accessor:
// re-resolve who we are whenever a different socket is carrying the calls
const [viewer] = createResource(conn.connectionEpoch, () =>
Effect.runPromise(conn.core.procedures.who.get({})),
);
It counts a usable connection being established, and only that:
| counts | |
|---|---|
| a reconnect inside the current wire generation | ✔ |
| a redial that lands on a connection — including the ordinary case where the replacement was already open, which the transport status has nothing to say about | ✔ |
a redial whose replacement is still connecting | ✔ when it opens, not when it is adopted |
| a redial whose dial failed | ✘ — no new connection was established, and the one you had is the one you still have |
- It reads 0 before the first connection, and is monotonic for the connection’s whole life: it does not restart with the underlying link.
- It is not a rebuild signal. Re-fetch what the connection itself answered, and leave the tree standing.
- A disposed connection is the one that answers about nothing: its
readoutreadsretiredand itshealthreads not-live, rather than freezing on whatever the disposed memo last computed. - The serve side’s half of the same contract is
implementRootedSurfaces, which is live, because a server’s siblings own stores, channels and running sources that must survive a roster change. serveSurfaceAppandserveOverUnixSockettake alivethunk of the generation;serveSurfaceSocketreads the pair per accepted connection.
The readout
A transport status answers a question about a socket, and an indicator makes a claim about a page. Those come apart in one place: a socket can be open and answering while a subscription riding it is dead. The fact that knows is client.health().
Both seams fold the two facts themselves and hand back readout, whose live is the conjunction.
degradednames what stopped, as a non-empty list, so “something isn’t arriving” is not spellable.pendingnever degrades.needsReloadmarks the one state a reload, and only a reload, recovers.- What each state is called stays yours: type your wording table
Record<SurfaceReadoutStatus, …>and a new state becomes a type error in your own file.
// The five states an indicator may report. `Record`, not a function: a state with
// no wording of its own is a type error HERE, in the app's own table, which is
// where the words belong. The framework decides which state is TRUE — including
// `degraded`, the one the transport cannot see (a live socket over a subscription
// that has stopped) — and this app decides what each is called.
const LABEL: Record<SurfaceReadoutStatus, string> = {
connecting: "connecting",
live: "live — everything this page reads is arriving",
degraded: "partly live",
reconnecting: "reconnecting — showing the last thing the server said",
retired: "the server was replaced — reload this page",
};
// `degraded` NAMES what stopped, and its list is non-empty by type, so this
// sentence can never come out with a hole in it.
const label = (): string => {
const now = readout();
return now.status === "degraded"
? `${LABEL.degraded} — nothing is arriving on ${now.stopped.join(", ")}`
: LABEL[now.status];
};
// The one bit that says a reload is the ONLY recovery (`retired`), read rather
// than re-derived — a page never has to keep its own list of terminal states.
const offerReload = (): boolean => readout().needsReload;
- A consumer that wants the socket rather than the page still has it:
link.wire.status()andlink.wire.onStatus, and (multi only) the brandedtransport.status. - There is deliberately no
heartbeat: falseon these seams. They mint the watchdog-backed brandsurfaceClientrequires, and a disabled watchdog would mint a branded-but-blind signal. - A wire whose liveness another layer owns does not use this seam.
The stale-tab handshake
Both seams own the pid handshake end to end. On every wire open they probe the framework-reserved system/identity member over the link’s own dispatch, and feed the processId it answers into the echo their URL thunk appends.
- Every reconnect therefore carries
?pid=<the process that served this page>, and the server’sgateStaleSocketcloses a tab bound to a process that is gone. - No app code observes an identity, and there is no returned
echofor an app to feed. - An app that shares one echo across several wires creates it itself, with
createProcessIdEcho()(@kolu/surface-app/connect), and passes it in.
retired
retired is required, and has no default:
| Option | Effect |
|---|---|
retired: () => void | Run once when the server retires this wire. This tab is bound to a process that no longer exists, the link has stopped dialling for good, and every call on it now fails with SurfaceTransportRetired |
retired: reloadForUpdateis the one-liner. Pass your own handler to take the screen instead.- Requiring it does not make an app render anything, but a wire that compiles has been asked what happens when it dies, and answered.
createServerLifecycle({ wire, probe })
It derives the connection lifecycle (connecting → connected → disconnected → reconnected / restarted) from the wire’s own status stream plus a processId probe.
- Pass
() => probeSurfaceIdentity(client.rpc)(@kolu/surface/identity), the framework-reserved round-trip every surface answers. - surface-app declares no identity member of its own. An
identity.infobesidebuildInfowould be two per-process ids in one server, and a stale-tab gate that works only while a consumer keeps them in step. - It observes a
WatchableWire(link.wire), not a socket object, so the same lifecycle rides any transport that can report status and force a re-dial. - Deriving a lifecycle cannot leave the wire un-watched. It owns a default-on half-open watchdog that probes on an interval and calls
wire.forceReconnect()when a probe times out, catching a socket that is TCP-dead with no FIN or RST (laptop sleep, Wi-Fi roam, NAT idle-eviction).
| Option | Effect |
|---|---|
livenessProbe | The watchdog’s round-trip. Pass () => probeSurfaceLive(client.rpc) so it asks the one reserved question, not an app-nominated verb. probe answers which process; this answers whether it answers at all |
heartbeat: false | Opt out of the default-on watchdog, only when you wire your own createHeartbeat. An object tunes intervalMs and timeoutMs and onStale, and observes every definitive verdict with onProbeSettled(ok, atMs) |
onProbeError | Surface a failed identity probe instead of silently holding the prior state |
- There is no
onStaleRestartand norestartCloseCode. The link owns the close-code classifier. - A
4001close retires the wire: statusretired, retry schedule halted, every call failing withSurfaceTransportRetired. The lifecycle reads that terminal status as a definitiverestarted, so nothing is left for a consumer to tear down at the decode site.
onClientError
onClientError?: (policy, err) => void is the app’s client error interpreter: the single seam an app registers so a member’s spec-declared client.onError policy reaches app code on a subscription failure. The policy comes from a surface built with defineSurfaceWithPolicy.
- Every door in the family takes it in the same position:
connectSurface(to its one client),connectSurfaces(threaded inward to every sibling and the root, viasurfaceClients→ eachbuildSurfaceClient),connectSurfaceMap, andsurfaceClientitself for a hand-built client. - So the app spells one interpreter, not one per surface.
- It is optional at the type. A policy-free surface needs none, but a member that does carry a policy makes
buildSurfaceClientthrow at construction if it was omitted, so a declared policy can never route nowhere.
createLiveSignal
surfaceClient over a websocket requires a watchdog-backed, branded LiveSignalHandle. A bare or unbranded wire dispatch throws, because it can half-open.
createLiveSignalis the only minter. It is re-exported on/solid, and lives in@kolu/surface/solidbeside its module-private brand.- The seams wrap it. A hand-built client calls it directly, passing the whole
{ dispatch, wire }the link factory minted, so the watchdog provably probes the transport it reconnects. - There is no
HostSessionexport; the per-host fleet seam isconnectSurface.
The client model
| Export | Subpath | What it is |
|---|---|---|
SurfaceAppProvider | /solid | The turnkey source for the stale-tab handshake and build identity. |
useSurfaceApp() | /solid | The headless model the shell is drawn from. |
SurfaceAppProvider
SurfaceAppProvider (@kolu/surface-app/solid) is the turnkey source that handles the stale-tab handshake.
- Its connection source is a union of
{ wire, probe }and{ status }. Pass the first and the provider derives the lifecycle off the link’sWatchableWire; pass the second when you already did. - There is no socket shape to satisfy.
- It takes a typed
controlPlanewhosebuildInfocell yields build identity, plusclientCommit={shellCommit()}. faultis required: the look of an uncaught render throw. See the fault boundary.
useSurfaceApp()
The headless model. No styled components ship.
| Accessor | Meaning |
|---|---|
status() | "live" | "reconnecting" | "restarted" | "down" |
presentingDown() | Grace-windowed down state. true only once status() has been not-live for DISCONNECT_OVERLAY_GRACE_MS (1 s), re-exported from @kolu/surface/solid and folded into a readout’s presentingDown |
server() | { commit, … } server identity |
reload() | Reload for an update |
setAttention(n) | OS app badge and title |
canInstallPwa() | True only in a secure context, and not already installed |
The fault boundary
A client that throws while drawing is not running the code that would draw any in-app error surface. Solid unmounts the subtree that faulted, and what a reader gets is a blank page with the truth in a console nobody opened. So the composition root takes the answer as a required prop, the way the connect seams require retired.
| Export | Subpath | What it is |
|---|---|---|
SurfaceFaultBoundary | /solid | Catches, records and prints an uncaught render throw. |
FaultLook | /solid | The one thing the app supplies: what that throw looks like. |
SurfaceFaultBoundary
The provider wraps its children in SurfaceFaultBoundary:
<SurfaceAppProvider fault={(text) => <Fault text={text} />} …>
It owns three verbs:
- It catches, with an
ErrorBoundaryaround the whole shell. - It records, with one
console.errornaming the moment. A boundary swallows, and Solid re-throws only when nothing catches, so without that line a faulted page fails a browser test as a bare timeout, with its “no page errors” assertion green. - It prints, with
thrownText, exported on.. The fault arrives asunknown(a string, anundefined, aDOMException), and the printer normalizes it, puts a Safari-lost message back on the front of its stack, and never returns the empty string.
An app whose root plumbing does not ride the provider composes the boundary directly:
render(
() => (
<SurfaceFaultBoundary fault={(text) => <Fault text={text} />}>
<App />
</SurfaceFaultBoundary>
),
root,
);
FaultLook
The app supplies only the look: FaultLook is (text: string) => JSX.Element, handed the printed text verbatim.
- That text is what a bug report is made of, and a look that summarized it would be the white tab with extra steps.
- Requiring the prop does not make an app render anything well, but a composition root that compiles has been asked what an uncaught throw looks like, and answered.
Build identity
Build identity is an interface: one export declares it, two implement it.
| Export | Subpath | What it is |
|---|---|---|
defineBuildInfo({ schema, default, isStale? }) | /surface | Declares the interface, and mints its cell. |
buildInfoServer({ buildInfo? }) | /server | Implements it on its own. |
surfaceAppServer({ buildInfo?, equals? }) | /server | Implements it as part of the app server. |
defineBuildInfo({ schema, default, isStale? })
Declares build identity. It lives on @kolu/surface-app/surface.
schemais an EffectWireSchema<T>.- The minted cell is
verbs: ["get"], so build identity is read-only on the wire and no client can fabricate or hide stale-client state. - The server still writes it, through
ctx.cells.buildInfo.set. - Read it with
app.cells.buildInfo.use({ authority: "server" }). The local{ initial }shape will not typecheck, because build identity is authoritative on the server.
buildInfoServer({ buildInfo? })
Implements the interface on its own, for a server that wants build identity and nothing else.
surfaceAppServer({ buildInfo?, equals? })
Implements it as part of the app server. equals decides when two build identities count as the same.
Service worker stance
No caching service worker, ever. The ban is on a fetch handler that intercepts the network, and it is definitional for this class of app.
| Export | Subpath | What it is |
|---|---|---|
SW_SOURCE | . | The self-destructing retirement worker, shipped by default. |
retireServiceWorker() | /lifecycle | Retires any worker a prior build registered. |
NOTIFICATION_SW_SOURCE | . | The one opt-in: a fetch-less notification worker. |
registerOrRetireServiceWorker() | /lifecycle | Registers that worker, or retires. |
Gate all service-worker logic on window.isSecureContext, never location.protocol === "https:".
SW_SOURCE
The worker the package ships by default: a self-destructing retirement worker at /sw.js.
retireServiceWorker()
Retires any worker a prior build registered.
NOTIFICATION_SW_SOURCE
The one opt-in: a fetch-less notification worker.
registerOrRetireServiceWorker()
Registers the notification worker, or retires. An app registers (notify) or retires (none), never both.
OS notifications
createNotify<D>(parse) (@kolu/surface-app/notify) is the last hop of cross-host attention: showing an OS notification from a PWA through the origin’s one service worker.
| Export | Subpath | What it is |
|---|---|---|
createNotify<D>(parse) | /notify | Builds the app’s notification seam. |
Notify<D> | /notify | What it returns: permission, show, click. |
createNotify<D>(parse)
It delivers through the fetch-less NOTIFICATION_SW_SOURCE worker above, and returns a Notify<D>.
Dis the app’s own click-routing payload shape. kolu’s is akind-discriminated union,{ kind: "host"; host; id } | { kind: "terminal"; host; terminalId }, so the one click router can never cross-deliver the two.- Both arms carry
host, so a click switches to the originating host before focusing. parse(data): D | undefinedvalidates each incoming click envelope. A malformed or stale payload is dropped, never routed.
Where delivery would hang or throw
Delivery is a framework piece, one seam at the origin’s one service worker, rather than N windows each attempting their own. Two things are why:
getRegistration(), never.ready.navigator.serviceWorker.readyresolves only when an active worker exists, so in any context where none registers (a dev server, a degraded boot) it hangs forever, silently killing the notification path.getRegistration()answers honestly, including “there isn’t one”.- The worker shows it, never
new Notification(). In an installed (standalone) PWA the page-context constructor throws “Illegal constructor”, so delivery must go throughregistration.showNotification().
Notify<D>
| Method | Role |
|---|---|
requestPermission() | Request OS permission. It resolves true when granted, and is idempotent. Delivery is a no-op until granted |
show({ tag, title, body?, icon?, data }) | Show a notification, or replace the same-tag one. A no-op where there is no worker, no active worker, or no permission |
onClick(handler) | Subscribe to clicks. The handler receives the clicked notification’s validated data. Returns an unsubscribe fn |
show
- A no-op here is never a throw or a hang. An operational failure is caught and logged, so a caller may fire-and-forget.
- The
tagcarries the multi-window discipline: two open windows must not both ping you. - A tag-keyed
showmakes the OS replace the same-tag notification instead of stacking a duplicate.
onClick
It covers two paths.
- The live path: the worker retries
postMessageunder an ack handshake, so a still-loading window that has not installed its listener yet does not drop the click. The page acks the exact delivering worker viaevent.source, so the ack lands even mid worker-replacement. - The cold-start URL handoff: with no window open, the worker opens one carrying the payload in
NOTIFICATION_DATA_PARAM, plus a click id inNOTIFICATION_CLICK_ID_PARAM, read once at startup. A loading window that never acks is navigated to the same URL as a durable fallback. - The click id dedups a live route against a fallback-navigate re-delivery, through a bounded
sessionStorageFIFO, so one click fires exactly one action. - Exactly-once is structural, not best-effort. The page routes the live message only when it can both ack the delivering worker (
event.sourcepresent) and durably record the id (sessionStoragewritable). - If either is missing, the page stays silent and lets the worker’s URL-fallback navigation be the single route. A storage failure is warned, never swallowed into a double-fire.
- The click payload comes back as the opaque
datathe app routes. The framework does not know what clicking attention means.