Phase 4: Server-Rendered First Paint

[SeanTAllen]

Phase 4: Server-Rendered First Paint

Implementation plan for Phase 4 of livery, derived from the design in #3.

Scope

Eliminates the empty-page flash on initial load. The HTTP server renders the LiveView to HTML at request time; the browser receives a fully populated page. When the JS client opens the WebSocket, the server mounts a fresh view (producing identical initial HTML), and morphdom silently takes over the pre-rendered DOM.

Deliverables:

1. Socket.connected() — distinguishes HTTP render from live WebSocket
2. PageRenderer — primitive that creates a temporary LiveView, mounts it, renders to HTML
3. PageRenderError — error union for factory/render failures
4. JS client detects pre-rendered content and uses morphdom (not innerHTML) for first render
5. Example: counter with server-rendered first paint
6. Tests for PageRenderer, Socket.connected(), and client pre-render handling

Design Decisions

Connection tokens are deferred

The design lists "embedded connection token for WebSocket handshake" as a Phase 4 feature. After analysis, tokens serve no functional purpose without authentication or sessions:

• No session bridging: The HTTP render and WebSocket mount are independent. Both call mount() from scratch, producing identical initial state. There's no state to transfer.
• No CSRF protection layer: Token validation requires a server-side token store or signing key infrastructure, neither of which exists yet.
• The WebSocket URL provides routing: The page embeds ws://host:port/path, which is sufficient to mount the correct LiveView.

Tokens should be added in a future phase alongside authentication/sessions, where they serve a real purpose. Adding them now would be ceremony without function.

PageRenderer takes a Factory, not Routes

PageRenderer.render(factory) rather than PageRenderer.render(routes, path).

The HTTP router (hobby) already matched the request to a handler before PageRenderer is called. The handler knows which Factory to use. Having PageRenderer re-match against livery's Routes would duplicate routing and require extracting the request path from the HTTP framework — an unnecessary coupling.

The Factory-based API is more composable: the caller handles routing (hobby does this naturally), and PageRenderer handles mount + render.

Socket: optional PubSub, connected flag

Rather than creating dummy PubSub actors for the render path, Socket's _pub_sub field becomes (PubSub tag | None). Subscribe/unsubscribe match on the field and no-op when None. This avoids creating throwaway actors and makes the disconnected state explicit in the type.

_self stays as InfoReceiver tag (always set) to keep self() non-partial. In the render path, a lightweight _NullInfoReceiver actor provides a valid but inert reference.

push_event continues to append to the pending events array unconditionally — in the render path the array is never flushed and gets GC'd with the rest of the temporary state. No conditional needed.

Hobby dependency is blocked by a lori version conflict

Hobby 0.2.0 depends on stallion 0.4.0, which requires lori 0.10.0. Mare 0.1.1 (livery's existing dependency) requires lori 0.8.5. Corral resolves each package to a single version, so adding hobby causes a conflict.

Options considered:

(A) Wait for mare to update to lori 0.10.0. Requires a PR to mare, a new mare release, and an update to livery's deps. This is the right long-term fix but blocks Phase 4 on work in another repo.

(B) Demonstrate SSR without hobby. The example uses a hand-written index.html with pre-rendered content. The library provides PageRenderer and the JS client supports pre-rendered takeover — both are fully implemented and tested — but the example doesn't dynamically generate the page via HTTP.

(C) Update mare ourselves as part of this work. Adds scope to the current phase.

Decision: Option B. The SSR example uses a static index.html with pre-rendered counter HTML already embedded in the lv-root div. This demonstrates the end-to-end UX (pre-rendered first paint → WebSocket takeover → morphdom) while keeping the library API complete (PageRenderer, Socket.connected()). The package docstring documents the full pattern including hobby integration, so users understand how to wire it together with a real HTTP server. When mare is updated, a follow-up adds hobby and converts the example to dynamic rendering.

A GitHub issue should be filed during implementation to track the hobby integration as a follow-up.

New example rather than updating counter

The design says "update existing counter." However, the current counter example is the simplest introduction to livery — changing it to require an HTTP server raises the barrier to entry. A separate ssr example preserves the simple counter and adds a focused SSR demonstration. Users compare the two to see what server-rendered first paint adds.

Dependencies

No new external dependencies. The hobby integration is deferred due to the lori version conflict (see design decision above).

Files

Create

livery/_null_info_receiver.pony — No-op actor satisfying InfoReceiver for disconnected sockets:

actor _NullInfoReceiver
  """
  No-op InfoReceiver for disconnected sockets. Messages sent to this actor
  are silently discarded. Used by PageRenderer to satisfy Socket's
  InfoReceiver field without a real connection.
  """
  be info(message: Any val) => None

livery/page_renderer.pony — PageRenderer primitive and PageRenderError type:

type PageRenderError is (PageRenderFactoryFailed | PageRenderFailed)

primitive PageRenderFactoryFailed
  """The Factory failed to create a LiveView instance."""
  fun string(): String iso^ => "factory_failed".clone()

primitive PageRenderFailed
  """The LiveView's render method failed."""
  fun string(): String iso^ => "render_failed".clone()

primitive PageRenderer
  """
  Render a LiveView to HTML without a WebSocket connection.

  Creates a temporary view, mounts it with a disconnected socket, and calls
  render. Use this for server-rendered first paint: generate HTML at HTTP
  request time, embed it in the page, and let the JS client take over when
  the WebSocket connects.

  The view is mounted with a disconnected socket — `connected()` returns
  false, PubSub operations are no-ops, and push events are silently dropped.
  LiveViews that need different behavior during HTTP render vs WebSocket can
  check `socket.connected()` in mount.
  """

  fun render(factory: Factory): (String val | PageRenderError) =>
    """
    Create a view from the factory, mount it, and render to HTML.

    Returns the rendered HTML string on success, or a specific error
    indicating whether the factory or the render failed.
    """
    let view = try factory()?
      else return PageRenderFactoryFailed
      end
    let assigns = Assigns
    let pending_events = Array[(String val, json.JsonValue)]
    let socket = Socket._for_render(assigns, pending_events)
    view.mount(socket)
    try
      view.render(assigns)?
    else
      PageRenderFailed
    end

examples/ssr/main.pony — Counter with server-rendered first paint:

Imports: use "templates", use "json", use lori = "lori", use "../../livery".

Same CounterView as the counter example — mount sets count to "0", handle_event increments/decrements, render uses HtmlTemplate.

Main creates routes and starts the WebSocket server on port 8084 (counter=8081, ticker=8082, form=8083). Identical to the counter example's Main, just a different port.

examples/ssr/index.html — HTML shell with pre-rendered content:

Unlike the other examples where <div id="lv-root"></div> is empty, this file has the counter's initial render already embedded:

<div id="lv-root">
  <div>
    <h1>Count: 0</h1>
    <button lv-click="increment">+</button>
    <button lv-click="decrement">-</button>
  </div>
</div>

The user sees the counter immediately on page load. When the WebSocket connects, the server mounts the same view (producing identical HTML), and morphdom silently takes over — no flash, no visible change.

This demonstrates the end-to-end UX. In production, PageRenderer.render(factory) would generate this HTML dynamically in an HTTP handler (e.g., hobby). The lori version conflict currently prevents adding hobby as a dependency (see design decisions).

Modify

livery/socket.pony — Add connected state and render-path constructor:

• New field: let _connected: Bool
• Change _pub_sub field type from PubSub tag to (PubSub tag | None)
• Update create constructor: set _connected = true, parameter type stays PubSub tag (widened to the union on assignment)
• New constructor: new _for_render(assigns, pending_events) — sets _connected = false, _pub_sub = None, creates _NullInfoReceiver for _self
• New method: fun box connected(): Bool — returns _connected, with docstring explaining the HTTP render vs WebSocket distinction
• Update subscribe and unsubscribe to match on _pub_sub, no-op when None:

fun ref subscribe(topic: String) =>
  match _pub_sub
  | let ps: PubSub tag => ps.subscribe(topic, _self)
  end

fun ref unsubscribe(topic: String) =>
  match _pub_sub
  | let ps: PubSub tag => ps.unsubscribe(topic, _self)
  end

The create constructor signature is unchanged — _Connection call sites don't need updating.

client/src/live-view.js — Detect pre-rendered content:

Change the render case in _handleMessage:

case "render":
  if (this._firstRender && !this._target.firstElementChild) {
    // No pre-rendered content: insert fresh
    this._target.innerHTML = msg.html;
  } else {
    // Pre-rendered takeover or subsequent update: morphdom patch
    morphdom(this._target.firstElementChild, msg.html);
  }
  this._firstRender = false;
  break;

When the target already has a child element (pre-rendered HTML from the HTTP response), the first WebSocket render uses morphdom instead of innerHTML. Since the pre-rendered HTML matches the initial WebSocket render (both mount from scratch with the same initial state), morphdom makes no visible changes — it silently takes over the DOM.

When the target is empty (no SSR), behavior is unchanged: innerHTML inserts the content.

livery/live_view.pony — Update trait docstrings:

• mount: Change "Called when the WebSocket connection is established" to reflect that mount is also called during HTTP rendering with a disconnected socket. Mention checking socket.connected() to distinguish the two contexts.
• render: Add note about single root element requirement — the returned HTML must have a single root element (e.g., wrapped in a <div>) for morphdom to work correctly.

livery/livery.pony — Update package docstring:

Add a "Server-Rendered First Paint" section documenting:

• What PageRenderer does and when to use it
• How Socket.connected() works and when to check it
• The lifecycle: HTTP render → page load → WebSocket connect → morphdom takeover
• Brief code snippet showing the pattern with hobby (as a usage guide, even though the hobby integration is deferred), including how to match on the three-arm return type (String val | PageRenderFactoryFailed | PageRenderFailed)

livery/_test.pony — Add tests (see Tests section).

client/test/live-view.test.js — Add tests (see Tests section).

examples/README.md — Add ssr example entry. Update the opening paragraph (which says all examples include an index.html) to note that the ssr example's index.html contains pre-rendered content. Add the ssr example to the running instructions table (port 8084).

CLAUDE.md — Update the file layout to add ssr/ under examples and page_renderer.pony / _null_info_receiver.pony under livery/. Add PageRenderer, PageRenderFactoryFailed, PageRenderFailed to the Public API section. Add _NullInfoReceiver to the Internal section. Update the Socket entry in Public API to mention connected().

Tests

Server-side (livery/_test.pony)

PageRenderer tests (example-based):

1. _TestPageRendererSuccess — factory that creates a valid view (minimal test view with a fixed template) → returns rendered HTML. Verify the returned string contains expected content.

2. _TestPageRendererFactoryFailed — factory that always errors → returns PageRenderFactoryFailed.

3. _TestPageRendererRenderFailed — factory that creates a view whose render always errors → returns PageRenderFailed.

These tests use test-only LiveView implementations (private test classes with \nodoc\). A _RenderTestView that renders a fixed template, and a _FailRenderView whose render always errors.

Socket.connected() tests:

4. _TestSocketConnectedTrue — Socket created via normal create constructor → connected() returns true.

5. _TestSocketConnectedFalse — Socket created via _for_render → connected() returns false.

6. _TestSocketDisconnectedSubscribeNoop — call subscribe("topic") and unsubscribe("topic") on a disconnected socket → no crash (verifies the match-on-None path works for both methods).

Client-side (client/test/live-view.test.js)

7. Pre-rendered content preserved: target has a child element before connect → first render message uses morphdom (the existing child node's identity is preserved, not replaced by innerHTML).

8. Empty target unchanged: target has no children → first render uses innerHTML. Verifies existing behavior is not broken.

9. Subsequent renders after takeover: after pre-rendered takeover, a second render message still uses morphdom normally.

Build and Verify

Server

make test ssl=openssl_3.0.x

Builds unit tests + all examples (including ssr). The Makefile auto-discovers example directories.

Client

cd client && npm test && npm run build

Files summary

File	Action
livery/_null_info_receiver.pony	Create
livery/page_renderer.pony	Create
livery/socket.pony	Edit
livery/live_view.pony	Edit
livery/livery.pony	Edit
livery/_test.pony	Edit
client/src/live-view.js	Edit
client/test/live-view.test.js	Edit
examples/ssr/main.pony	Create
examples/ssr/index.html	Create
examples/README.md	Edit
CLAUDE.md	Edit
GitHub issue: hobby integration follow-up	Create

[SeanTAllen]

Implemented in #20.