Phase 6: Static/Dynamic Splitting — Implementation Plan

[SeanTAllen]

Design: #3

This is the implementation plan for Phase 6 of the livery design. The goal is wire efficiency: send only changed dynamic values instead of full HTML on every state change. Static template parts get sent once per connection, and subsequent renders send only the dynamic slots that changed.

The design document says "This is an internal optimization — the LiveView trait stays the same." The plan interprets that as backward compatible: existing views compile and work unchanged. But it does add a new defaulted method to the trait, so that interpretation needs discussion before implementation starts.

How It Works

Templates already parse into static text and dynamic expressions internally. Phase 6 exposes that split through a new render_split() method on HtmlTemplate, which returns (statics, dynamics) arrays instead of a concatenated string. The statics are fixed at parse time; the dynamics change on each render. The framework tracks previous dynamics per connection and sends only the slots that changed.

Views opt in by overriding a new render_parts() method on LiveView. The default returns None, which tells the framework to use the existing full-HTML path. Views that override it get the split protocol. Views that don't change nothing.

Invariants

1. Statics are fixed per template instance. statics.size() == dynamics.size() + 1 always holds.
2. Full HTML is always reconstructable from statics[0] + dynamics[0] + statics[1] + ... + statics[N].
3. Reconstruction equivalence. assemble(render_split(values)) == render(values) for all values. This is the core correctness property and the most important test.
4. Reconnection resets state. New _Connection actor = fresh state. Server sends statics + all dynamics on every new connection.
5. Escaping is server-side. Dynamic slot values are pre-escaped by HtmlTemplate's contextual auto-escaping. The client concatenates pre-escaped strings.
6. PageRenderer is unaffected. SSR produces full HTML via render(). The split protocol is WebSocket-only.

Design Decision: Partial vs Non-Partial

render() is partial because rendering can fail and the framework must handle it. render_parts() is non-partial, returning (RenderParts | None). None means both "I don't support split rendering" and "split rendering failed" — the framework's response to both is the same: fall back to render(). This makes the framework simpler but creates an inconsistency between the two render methods.

This needs discussion before implementation.

Steps

Step 1: Add render_split to the Templates Library

Repo: ponylang/templates (separate PR, release as 0.4.0)

One new method on HtmlTemplate and Template:

fun render_split(values: TemplateValues box)
  : (Array[String val] val, Array[String val] val) ?

Returns (statics, dynamics). For N dynamic slots, statics has N+1 entries and dynamics has N entries.

Statics are precomputed at parse time and cached as let _statics: Array[String val] val on the template. Subsequent calls return the same cached val reference, enabling cheap identity comparison (is) by callers.

The implementation is a new _render_parts_split that walks _parts the same way _render_parts does:

• _Literal text: append to current static accumulator
• Dynamic nodes (_PropNode, _Pipe): flush static accumulator, evaluate expression with escaping via _HtmlContextTracker, add result to dynamics array, start new static accumulator
• Control flow (_If, _IfNot, _Loop, _Block): flush static accumulator, render entire block to a single string using existing _render_parts recursion, add as one dynamic slot
• After the loop, flush the final static accumulator

HTML context tracking feeds static literals through _HtmlContextTracker exactly as render does, so dynamic expressions get correct contextual escaping. Both methods walk the same AST with the same tracker; the difference is only in output collection.

Control flow nodes become single opaque slots. When {{ if flag }}content{{ end }} appears, the inner content becomes part of a dynamic slot value, not a static segment. The statics array is identical regardless of which branch is taken. Includes and inheritance are already resolved at parse time by _ParserCommon, so render_split just walks the final resolved _parts array.

If two {{ }} blocks have no text between them, render_split inserts an empty string in the statics array between them to maintain the interleaving invariant.

Edge cases:

• Empty template: statics = [""], dynamics = []
• Only literals: statics = ["the text"], dynamics = []
• Only a variable: statics = ["", ""], dynamics = [value]

Tests (in templates repo):

• statics.size() == dynamics.size() + 1 for various templates
• Reconstruction roundtrip property (PonyCheck): assemble(statics, dynamics) == render(values) for random values
• Conditionals with different branches produce identical statics arrays
• Loops produce identical statics regardless of iteration count
• Adjacent dynamic parts produce empty-string statics between them
• HTML escaping in dynamics matches render() output
• Statics identity caching: two calls on same template return same statics reference
• Counterfactual: break reconstruction assertion, verify it fires

Step 2: Update Livery's Templates Dependency

Update corral.json to templates 0.4.0.

Step 3: Add RenderParts Public Type

New file: livery/render_parts.pony

class val RenderParts
  """
  Result of a split render: static text fragments and dynamic slot values.

  The full HTML is reconstructed by interleaving statics and dynamics:
  `statics[0] + dynamics[0] + statics[1] + dynamics[1] + ... + statics[N]`

  `statics.size()` is always `dynamics.size() + 1`.
  """
  let statics: Array[String val] val
  let dynamics: Array[String val] val

  new val create(statics': Array[String val] val,
    dynamics': Array[String val] val)
  =>
    statics = statics'
    dynamics = dynamics'

  fun full_html(): String val =>
    """
    Reconstruct the full HTML string from statics and dynamics.
    """
    // Interleave statics[i] + dynamics[i], append final statics element

The constructor is non-partial because render_split() guarantees the interleaving invariant by construction.

Tests:

• Known statics/dynamics produce expected HTML
• Empty dynamics assembles correctly
• PonyCheck: full_html() of random valid parts equals manual interleave
• Counterfactual on full_html

Step 4: Add render_parts to LiveView

File: livery/live_view.pony

fun box render_parts(assigns: Assigns box): (RenderParts | None) =>
  """
  Return structured render output for efficient wire updates.

  When this returns a RenderParts, the framework sends static template
  parts once per connection and only changed dynamic slot values on
  subsequent renders. When it returns None (the default), the framework
  falls back to render() and sends full HTML.

  Override this to enable split rendering. Typical implementation:

      fun box render_parts(assigns: Assigns box): (RenderParts | None) =>
        try
          (let s, let d) = _template.render_split(assigns.template_values())?
          RenderParts(s, d)
        end
  """
  None

LiveComponent does not get render_parts in this phase. Component output is flattened to a string for injection into the parent's template values via component_html(). The framework can't use structured component output without restructuring the component registry and wire format. Component-level split rendering is deferred.

Step 5: Add _RenderState Internal Type

New file: livery/_render_state.pony

Per-connection state for diff computation:

class _RenderState
  var _statics: (Array[String val] val | None) = None
  var _prev_dynamics: (Array[String val] val | None) = None

update(parts: RenderParts): _RenderDiff compares statics by identity (is), dynamics by element-wise string equality. Returns _FullRender on first render or template change, _SlotDiff for partial changes, _NoChange if all slots match.

Types: _RenderDiff is (_FullRender | _SlotDiff | _NoChange)

Statics identity comparison works because HtmlTemplate caches statics as a val field — same template instance, same reference. If a user switches templates mid-session, identity differs, triggering a full render. A false positive (different instance, same content) just causes a harmless redundant full render.

Defensive: if prev_dynamics.size() != new_dynamics.size(), return _FullRender.

Tests:

• First update returns _FullRender
• Same dynamics returns _NoChange
• Changed slots return _SlotDiff with correct indices
• Different statics reference returns _FullRender
• PonyCheck: diff contains exactly the indices where values differ

Step 6: Update Wire Protocol

File: livery/_wire_protocol.pony

Two new message types alongside the existing encode_render:

render_full: {"t":"render_full","s":["<div>","</div>"],"d":["42"]}
render_diff:  {"t":"render_diff","d":{"0":"43","2":"new_value"}}

render_full sends statics + all dynamics (first render or template change). render_diff sends only changed slot indices as string keys mapping to new values. The existing encode_render(html) is preserved for the full-HTML fallback path.

Tests:

• encode_render_full JSON structure
• encode_render_diff JSON with string keys
• Empty changes produce empty d object

Step 7: Update _Connection for Split Rendering

File: livery/_connection.pony

Add let _render_state: _RenderState ref = _RenderState.

Both on_open and _maybe_rerender get a dual path:

fun ref _maybe_rerender(v: LiveView ref) =>
  let components_changed = _components.render_all()
  for err in _components.flush_render_errors().values() do
    _ws.send_text(_WireProtocol.encode_error(err))
  end
  if _assigns.changed() or components_changed then
    _components.populate_component_html(_assigns)
    match v.render_parts(_assigns)
    | let parts: RenderParts =>
      match _render_state.update(parts)
      | let full: _FullRender =>
        _last_html = parts.full_html()
        _ws.send_text(
          _WireProtocol.encode_render_full(full.statics, full.dynamics))
      | let diff: _SlotDiff =>
        _last_html = parts.full_html()
        _ws.send_text(_WireProtocol.encode_render_diff(diff.changes))
      | _NoChange => None
      end
    | None =>
      try
        let html = v.render(_assigns)?
        _last_html = html
        _ws.send_text(_WireProtocol.encode_render(html))
      else
        _ws.send_text(_WireProtocol.encode_error("render_failed"))
      end
    end
    _assigns.clear_changes()
    _assigns._clear_component_html()
  end
  _flush_pending_events()

When components change, populate_component_html updates the assigns. The view's render_parts produces dynamics that include the component HTML as an unescaped slot value. _RenderState detects the changed slot via string comparison. No changes to _ComponentRegistry needed.

Step 8: No Changes to Component Registry or PageRenderer

Components render to full HTML strings via render(). A component's output occupies one dynamic slot in the parent. Component-level split rendering is deferred.

PageRenderer calls view.render(assigns) and returns full HTML. The split protocol is _Connection-only.

Step 9: Update JS Client Wire Module

File: client/src/wire.js

case "render_full":
  return { type: "render_full", statics: obj.s, dynamics: obj.d };
case "render_diff":
  return { type: "render_diff", dynamics: obj.d };

Existing "render" case preserved for the full-HTML fallback.

Tests: decode render_full, render_diff, legacy render regression, empty dynamics, multiple changed slots.

Step 10: Update JS Client LiveView

File: client/src/live-view.js

Add _statics and _dynamics state. Extract morphdom/innerHTML into _applyHtml(html). Add _assembleHtml(statics, dynamics).

case "render_full":
  this._statics = msg.statics;
  this._dynamics = [...msg.dynamics];
  this._applyHtml(this._assembleHtml(this._statics, this._dynamics));
  break;
case "render_diff":
  if (!this._statics || !this._dynamics) break;
  for (const [idx, val] of Object.entries(msg.dynamics)) {
    const i = parseInt(idx, 10);
    if (i >= 0 && i < this._dynamics.length) {
      this._dynamics[i] = val;
    }
  }
  this._applyHtml(this._assembleHtml(this._statics, this._dynamics));
  break;
case "render":
  this._applyHtml(msg.html);
  break;

Clear _statics and _dynamics on reconnect. Bounds-check diff indices to prevent malformed messages from corrupting the array.

Tests: render_full renders, render_diff patches, diff before full ignored, reconnect resets, legacy render works, SSR + split, out-of-bounds diff ignored.

Step 11: Update Examples

Views with derived render-time computation (like the todo example building items_html from component HTML) use a _prepare_values helper to share logic between render and render_parts:

fun box _prepare_values(assigns: Assigns box): TemplateValues =>
  let vals = assigns.render_values()
  var items = ""
  for id in _todo_ids.values() do
    try items = items + assigns.component_html(id)? end
  end
  vals.unescaped("items_html", items)
  vals

fun box render(assigns: Assigns box): String ? =>
  _template.render(_prepare_values(assigns))?

fun box render_parts(assigns: Assigns box): (RenderParts | None) =>
  try
    (let s, let d) = _template.render_split(_prepare_values(assigns))?
    RenderParts(s, d)
  end

All five examples (counter, ticker, form, todo, ssr) add render_parts overrides. Update examples/README.md.

Step 12: Tests

Build/run: make test ssl=openssl_3.0.x (server), make client-test (JS). All new test classes get \nodoc\. Counterfactual testing after each new test passes.

Server tests in livery/_test.pony:

Test	Type	Verifies
_RenderPartsFullHtml	Example	Known statics/dynamics produce expected HTML
_RenderPartsEmptyDynamics	Example	Statics-only template assembles correctly
_RenderPartsInterleave	PonyCheck	full_html() matches manual interleave
_TestRenderStateFirstRender	Example	First update returns _FullRender
_TestRenderStateNoDiff	Example	Same dynamics returns _NoChange
_TestRenderStatePartialDiff	Example	Changed slots return _SlotDiff
_TestRenderStateStaticsChanged	Example	Different statics returns _FullRender
_RenderStateDiffProperty	PonyCheck	Diff has exactly the changed indices
_TestEncodeRenderFull	Example	Correct JSON structure
_TestEncodeRenderDiff	Example	Correct JSON with string keys
_TestEncodeRenderDiffEmpty	Example	Empty changes produce empty d object
_TestLiveViewRenderPartsDefault	Example	Default returns None

JS tests: decode render_full, decode render_diff, legacy render regression, render_full renders, render_diff patches, diff before full ignored, reconnect resets, out-of-bounds ignored, legacy render works, SSR + split.

Step 13: Update Documentation

CLAUDE.md: add RenderParts and render_parts() to public API, _RenderState and friends to internals, render_full/render_diff to wire protocol, new files to layout, update conventions for PonyCheck coverage.

Package docstring (livery/livery.pony): add section on split rendering.

Examples README: update descriptions.

Implementation Order

Step 1: Templates library PR (critical path)
  |  release 0.4.0
Step 2: Update corral.json
  |
Steps 3-6 in parallel:
  Step 3: RenderParts type
  Step 4: LiveView trait addition
  Step 5: _RenderState
  Step 6: Wire protocol encoding
  |
Step 7: _Connection integration (depends on 3-6)
  |
Steps 8: Verify no changes needed (components, PageRenderer)
Steps 9-10: JS client changes (can parallel with Step 7)
  |
Steps 11-13: Examples, tests, documentation

Files Changed

New files:

• livery/render_parts.pony — RenderParts public class
• livery/_render_state.pony — _RenderState, _RenderDiff, _FullRender, _SlotDiff, _NoChange

Modified files:

• corral.json — templates 0.4.0
• livery/live_view.pony — add render_parts()
• livery/_wire_protocol.pony — encode_render_full(), encode_render_diff()
• livery/_connection.pony — _render_state, dual render path
• livery/_test.pony — all new tests
• livery/livery.pony — package docstring
• client/src/wire.js — decode new message types
• client/src/live-view.js — statics/dynamics state, assembly, dual message handling
• client/test/wire.test.js — new decode tests
• client/test/live-view.test.js — new render tests
• examples/counter/main.pony — render_parts override
• examples/ticker/main.pony — render_parts override
• examples/form/main.pony — render_parts override
• examples/todo/main.pony — render_parts override with _prepare_values
• examples/ssr/main.pony — render_parts override
• examples/README.md
• CLAUDE.md

Unchanged: assigns.pony, socket.pony, component_socket.pony, factory.pony, page_renderer.pony, info_receiver.pony, _null_info_receiver.pony, pub_sub.pony, router.pony, listener.pony, _component_registry.pony, _unreachable.pony, live_component.pony, client/src/socket.js, client/src/events.js

Co-deployment Assumption

The JS client and Pony server live in the same repository and are deployed together. VERSION is 0.0.0. No wire protocol backward compatibility is needed between different client/server versions.

Open Questions

1. "LiveView trait stays the same" — how strict? Adding render_parts() with a default None is backward compatible (existing views compile and work unchanged), but it adds a new method. If this violates the intent, the alternative is a registration-based approach like Socket.register_split_template() in mount().

2. Partial vs non-partial render_parts? The plan proposes non-partial (returns None on error). This is simpler for the framework but inconsistent with render() being partial. Should render_parts be partial too?

3. Performance of string comparison for large opaque slots. Control flow blocks that render many items (a loop with 100 entries) produce one big dynamic string that gets compared every cycle. A future optimization could track assign-to-slot dependencies.

4. Render method duplication. Views need both render() (for PageRenderer) and render_parts() (for WebSocket). The _prepare_values helper pattern mitigates this for views with derived values, but both methods still exist.

[SeanTAllen]

Closed in favor of #30