Phase 6: Static/Dynamic Splitting — Refined Plan (v2)

[SeanTAllen]

Design: #3
Predecessors: #28, #29

This plan replaces Discussion #29. The core approach is the same -- split template output into static and dynamic parts, send only changed dynamics over the wire -- but the API is simpler, the implementation is leaner, and a critical dependency question is resolved: templates 0.3.2 already ships render_to(sink), TemplateSink, and render_split(). No separate templates PR is needed. Just bump the version.

What Changed from #29

Discussion #29 was built on templates 0.3.1. It planned adding render_split() to the templates library as a separate PR, releasing templates 0.4.0, then consuming it. Templates 0.3.2 already has all of that. This eliminates the critical-path dependency and the most complex step in the old plan.

The API also changes substantially. #29 had views return a RenderParts value from render_parts(). This plan has the framework pass a sink to the view, which the view feeds to HtmlTemplate.render_to(). The sink collects statics and dynamics, caches statics across renders, and computes diffs in a single pass. No new public types are introduced.

How It Works

Templates parse into static text and dynamic expressions internally. HtmlTemplate.render_to(sink, values) drives a caller-supplied TemplateSink with alternating literal() and dynamic_value() calls. The framework creates one persistent _RenderSink per connection, passes it to the view's render_parts() method, and the view feeds it to the template. The sink tracks previous dynamics, compares inline during the walk, and returns the minimal diff.

Views opt in by overriding render_parts() on the LiveView trait. The default returns false (not supported), and the framework falls back to the existing render() path. Views that override it get the split protocol. Views that don't change nothing.

API

LiveView Trait Addition

fun box render_parts(assigns: Assigns box,
  sink: templates.TemplateSink ref): Bool
=>
  """
  Drive the given sink with static/dynamic template output for efficient
  wire updates.

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

  Override this to enable split rendering. Typical implementation:

      fun box render_parts(assigns: Assigns box,
        sink: templates.TemplateSink ref): Bool
      =>
        try
          _template.render_to(sink, assigns.template_values())?
          true
        else
          false
        end
  """
  false

The parameter type is templates.TemplateSink ref, not a livery-specific type. The view depends only on the templates library's interface. The framework passes its internal _RenderSink (which implements TemplateSink) but the view doesn't know or care about that -- it just passes the sink to _template.render_to().

This is backward compatible. Existing views compile and work unchanged. The handle_info precedent supports adding defaulted methods to traits.

LiveComponent does not get render_parts. Component output is flattened to a string for injection into the parent's template values via component_html(). Component-level split rendering is deferred.

No New Public Types

Zero new public types are introduced. The view method takes TemplateSink ref (already public in templates) and returns Bool. The sink implementation, diff types, and all rendering state are internal. This follows the principle that it's easier to add public API later than to remove it.

Compare with #29, which introduced RenderParts as a public class. That type existed only to shuttle data from the view to the framework -- it had no behavior beyond full_html() reconstruction. With the sink approach, the framework already has the data; no shuttle type is needed.

Internal Architecture

_RenderSink (new file: livery/_render_sink.pony)

Implements TemplateSink. One instance per connection, owned by _Connection. Handles everything: collecting statics and dynamics, caching statics across renders, verifying statics haven't changed, computing incremental diffs, and reconstructing full HTML.

The sink uses a transaction pattern:

1. Framework calls begin() before each render
2. View drives _template.render_to(sink, values) which calls literal() and dynamic_value() alternately
3. Framework calls result() to get the diff, or abandon() if the view returned false

class _RenderSink is templates.TemplateSink
  """
  Persistent per-connection sink that collects template output, caches
  statics, and computes incremental diffs between successive renders.

  Transaction lifecycle: begin() -> literal/dynamic_value calls -> result().
  On render failure: begin() -> abandon().
  On fallback to full-HTML: clear() discards all cached state.
  """
  // Cached state from previous render
  var _cached_statics: (Array[String] val | None) = None
  var _prev_dynamics: (Array[String] val | None) = None

  // Transient state for the current render
  var _temp_statics: Array[String] iso = recover iso Array[String] end
  var _temp_dynamics: Array[String] iso = recover iso Array[String] end
  var _temp_changes: Array[(USize, String)] iso =
    recover iso Array[(USize, String)] end
  var _dynamic_index: USize = 0
  var _statics_mismatch: Bool = false

  fun ref begin() =>
    """
    Start a new render transaction. Resets transient state while preserving
    cached statics and previous dynamics.
    """
    _temp_statics = recover iso Array[String] end
    _temp_dynamics = recover iso Array[String] end
    _temp_changes = recover iso Array[(USize, String)] end
    _dynamic_index = 0
    _statics_mismatch = false

  fun ref literal(text: String) =>
    """
    Receive a static template segment. On subsequent renders, verifies the
    segment matches the cached statics at the same position via content
    comparison.
    """
    match _cached_statics
    | let cached: Array[String] val =>
      try
        if cached(_temp_statics.size())? != text then
          // Content mismatch -- template changed
          _statics_mismatch = true
        end
      else
        // More statics than cached -- template changed
        _statics_mismatch = true
      end
    end
    _temp_statics.push(text)

  fun ref dynamic_value(value: String) =>
    """
    Receive a dynamic value. Simultaneously stores the value and compares
    against the previous dynamics at the same index, building the changes
    list inline.
    """
    let idx = _dynamic_index
    _dynamic_index = _dynamic_index + 1
    _temp_dynamics.push(value)

    match _prev_dynamics
    | let prev: Array[String] val =>
      try
        if prev(idx)? != value then
          _temp_changes.push((idx, value))
        end
      else
        // More dynamics than before -- template changed, will be caught
        // by statics mismatch or size mismatch in result()
        _temp_changes.push((idx, value))
      end
    else
      // First render -- all dynamics are "changes"
      _temp_changes.push((idx, value))
    end

  fun ref result(): _RenderDiff =>
    """
    Finalize the current render and return the diff.

    Destructively reads the transient arrays, converting them to val.
    Updates cached statics and previous dynamics.
    """
    let new_statics: Array[String] val =
      _temp_statics = recover iso Array[String] end
    let new_dynamics: Array[String] val =
      _temp_dynamics = recover iso Array[String] end
    let changes: Array[(USize, String)] val =
      _temp_changes = recover iso Array[(USize, String)] end

    // Check for statics mismatch (count or content)
    let statics_changed = _statics_mismatch
      or match _cached_statics
        | let cached: Array[String] val =>
          cached.size() != new_statics.size()
        | None => true
        end

    // Update cached state
    _cached_statics = new_statics
    _prev_dynamics = new_dynamics

    if statics_changed then
      _FullRender(new_statics, new_dynamics)
    elseif changes.size() == 0 then
      _NoChange
    else
      _SlotDiff(changes)
    end

  fun ref abandon() =>
    """
    Discard the current render's transient state without updating caches.
    Used when the view's render_parts() returns false.
    """
    _temp_statics = recover iso Array[String] end
    _temp_dynamics = recover iso Array[String] end
    _temp_changes = recover iso Array[(USize, String)] end
    _dynamic_index = 0
    _statics_mismatch = false

  fun ref clear() =>
    """
    Discard all state -- cached and transient. Used when a view falls back
    from split rendering to full-HTML rendering, so stale state doesn't
    persist across the transition.
    """
    _cached_statics = None
    _prev_dynamics = None
    abandon()

  fun full_html(): String val =>
    """
    Reconstruct the full HTML from the most recent render's statics and
    dynamics. Used by _Connection to update _last_html for error recovery.
    """
    match (_cached_statics, _prev_dynamics)
    | (let s: Array[String] val, let d: Array[String] val) =>
      var total: USize = 0
      for str in s.values() do total = total + str.size() end
      for str in d.values() do total = total + str.size() end
      recover val
        let out = String(total)
        var i: USize = 0
        try
          while i < d.size() do
            out.append(s(i)?)
            out.append(d(i)?)
            i = i + 1
          end
          out.append(s(i)?)
        else
          _Unreachable()
        end
        out
      end
    else
      ""
    end

Capability notes:

• _temp_statics, _temp_dynamics, and _temp_changes are iso fields. The destructive read pattern (let x: T val = _field = recover iso ... end) converts them to val cleanly -- same pattern used by _SplitSink in the templates library.
• push() on iso arrays works via automatic receiver recovery.
• In full_html(), the recover val block cannot access this fields. The fields _cached_statics and _prev_dynamics are read into local val variables (s, d) before the recover block. Both are Array[String] val (sendable), so the locals are accessible inside recover.

Statics verification: On subsequent renders, each literal() call compares the incoming text against the cached statics at the same index using != (content comparison). Identity comparison (is) would be cheaper but doesn't work here -- _TemplateWalk accumulates literal segments in a pending: String ref buffer and flushes pending.clone() to the sink, producing a fresh String val allocation each render. Same template, different object identity.

Content comparison catches template switches reliably: if a view changes its HtmlTemplate instance mid-session (e.g., switching between a "logged in" and "logged out" template with the same variable count), the statics content will differ and the sink detects it, triggering a _FullRender with the new statics.

A size check (cached count vs. new count) in result() provides an O(1) early-out for structural template changes (different number of dynamic slots). The per-literal != check catches same-structure-different-content changes. For typical templates (3-10 static fragments, each 10-100 bytes), verification adds a few microseconds per render. String.eq() does a size check first, so mismatches on length short-circuit immediately.

One-pass diff: Each dynamic_value() call simultaneously stores the value and compares against _prev_dynamics at the same index. Changes are accumulated inline in _temp_changes. No separate diff pass after the walk.

_RenderDiff Types (in livery/_render_sink.pony)

type _RenderDiff is (_FullRender | _SlotDiff | _NoChange)

class val _FullRender
  """First render or template change -- send statics + all dynamics."""
  let statics: Array[String] val
  let dynamics: Array[String] val

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

class val _SlotDiff
  """Only some dynamic slots changed -- send changed indices and values."""
  let changes: Array[(USize, String)] val

  new val create(changes': Array[(USize, String)] val) =>
    changes = changes'

primitive _NoChange
  """All dynamic slots match the previous render -- send nothing."""

Wire Protocol Changes (livery/_wire_protocol.pony)

Two new encoding functions alongside the existing encode_render:

fun encode_render_full(statics: Array[String] val,
  dynamics: Array[String] val): String val
=>
  """
  Encode a full split render: statics + all dynamics.
  Sent on first render or when the template changes.
  """
  var s_arr = json.JsonArray
  for s in statics.values() do
    s_arr = s_arr.push(s)
  end
  var d_arr = json.JsonArray
  for d in dynamics.values() do
    d_arr = d_arr.push(d)
  end
  json.JsonObject
    .update("t", "render_full")
    .update("s", s_arr)
    .update("d", d_arr)
    .string()

fun encode_render_diff(
  changes: Array[(USize, String)] val): String val
=>
  """
  Encode a partial update: only changed dynamic slot values.
  String keys for slot indices (e.g., {"0": "val", "2": "new"}).
  """
  var d_obj = json.JsonObject
  for (idx, value) in changes.values() do
    d_obj = d_obj.update(idx.string(), value)
  end
  json.JsonObject
    .update("t", "render_diff")
    .update("d", d_obj)
    .string()

Wire format:

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

The existing encode_render(html) is preserved for the full-HTML fallback path.

_Connection Changes (livery/_connection.pony)

Add let _render_sink: _RenderSink ref = _RenderSink as a field.

Extract the dual render path into a _try_split_render helper to avoid duplicating the logic between on_open and _maybe_rerender:

fun ref _try_split_render(v: LiveView ref): Bool =>
  """
  Attempt a split render. Returns true if the split path handled rendering
  (even if the diff was _NoChange). Returns false if the view doesn't
  support split rendering, meaning the caller should fall back to render().
  """
  _render_sink.begin()
  if v.render_parts(_assigns, _render_sink) then
    match _render_sink.result()
    | let full: _FullRender =>
      _last_html = _render_sink.full_html()
      _ws.send_text(
        _WireProtocol.encode_render_full(full.statics, full.dynamics))
    | let diff: _SlotDiff =>
      _last_html = _render_sink.full_html()
      _ws.send_text(
        _WireProtocol.encode_render_diff(diff.changes))
    | _NoChange => None
    end
    true
  else
    _render_sink.abandon()
    false
  end

Both on_open and _maybe_rerender use this helper:

on_open render section (replaces lines 62-70):

if not _try_split_render(view) then
  try
    let html = view.render(_assigns)?
    _last_html = html
    _ws.send_text(_WireProtocol.encode_render(html))
  else
    _ws.send_text(_WireProtocol.encode_error("render_failed"))
    _ws.close()
    return
  end
end

_maybe_rerender -- with fallback transition handling:

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)
    if not _try_split_render(v) then
      _render_sink.clear()
      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()

The _render_sink.clear() call in the fallback path discards stale cached state when a view transitions from split rendering back to full-HTML. Without this, a subsequent switch back to split rendering would compare against stale dynamics from a previous split session.

JS Client Changes

client/src/wire.js -- two new cases in decodeServerMessage:

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

The existing "render" case is preserved.

client/src/live-view.js -- add _statics and _dynamics state, extract _applyHtml, add _assembleHtml:

constructor(opts) {
  // ... existing setup ...
  this._statics = null;
  this._dynamics = null;

  this._socket = new Socket({
    // ... existing config ...
    onOpen: () => {
      // Reset split state on reconnect
      this._statics = null;
      this._dynamics = null;
      this._events = setupEventDelegation(/* ... */);
    },
    // ...
  });
}

_applyHtml(html) {
  if (this._target.firstElementChild) {
    morphdom(this._target.firstElementChild, html);
  } else {
    this._target.innerHTML = html;
  }
}

_assembleHtml(statics, dynamics) {
  let html = "";
  for (let i = 0; i < dynamics.length; i++) {
    html += statics[i] + dynamics[i];
  }
  html += statics[dynamics.length];
  return html;
}

_handleMessage(msg) {
  switch (msg.type) {
    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":
      // Full-HTML fallback -- clear split state
      this._statics = null;
      this._dynamics = null;
      this._applyHtml(msg.html);
      break;
    // ... push, error unchanged ...
  }
}

Key behaviors:

• Reconnect resets split state. _statics and _dynamics are cleared in onOpen.
• render_diff before render_full is silently dropped. The guard prevents corrupted state.
• Out-of-bounds diff indices are ignored. Bounds check prevents malformed messages from corrupting the array.
• Legacy render clears split state. Handles fallback transition cleanly.

Invariants

1. Statics are fixed per template instance. statics.size() == dynamics.size() + 1 always holds. This is enforced by the templates library's _TemplateWalk interleaving guarantee.
2. Full HTML is always reconstructable from statics[0] + dynamics[0] + statics[1] + ... + statics[N].
3. Reconstruction equivalence. Feeding _RenderSink via render_to() and reconstructing with full_html() produces the same string as HtmlTemplate.render() for identical values. This is the core correctness property.
4. Reconnection resets state. New _Connection actor = fresh _RenderSink. 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 without further processing.
6. PageRenderer is unaffected. SSR produces full HTML via render(). The split protocol is WebSocket-only.

Performance Analysis

Wire Bandwidth

Example	Full render	render_full (first)	render_diff (subsequent)	Savings
Counter (~170 bytes)	170 bytes	~200 bytes	~15 bytes	Break-even after 2 renders
Form (~530 bytes)	530 bytes	~550 bytes	~30 bytes (1 field)	17x reduction per update
Todo (variable)	variable	variable	limited (1 large opaque slot)	Marginal until component-level splitting

The first message is roughly 18% larger than full-HTML due to the statics array. Break-even occurs after 2 renders for any view. Every interactive view gets more than 2 renders per connection.

Memory Per Connection

_RenderSink stores: cached statics reference (8 bytes), previous dynamics array (~8N bytes of pointers + string data), transient arrays (reset each render). Counter: trivial. Form (7 slots): ~56 bytes of pointers. A 50-slot template: ~400 bytes of pointers.

CPU: One-Pass Diff

Each dynamic_value() call does one array lookup and one string comparison against the previous value. For N slots, that's N comparisons during the walk -- no separate pass. Statics verification adds N+1 content comparisons (!=) on static fragments. For typical templates (N < 20, statics averaging 10-100 bytes each), String.eq() short-circuits on size mismatch and the total verification cost is low microseconds -- negligible relative to template evaluation.

Interface Dispatch

HtmlTemplate.render_to() dispatches literal() and dynamic_value() calls through the TemplateSink interface -- that's 2N+1 virtual dispatch calls per render. This cost is inherent to using render_to(), not specific to our API choice. For N=20, roughly 40ns of dispatch overhead -- orders of magnitude below template evaluation cost.

Steps

Step 1: Update Templates Dependency

Update corral.json from templates 0.3.1 to 0.3.2. Run make clean before rebuilding -- when a dependency changes versions, corral fetch may leave stale files from the old checkout in _corral/.

Templates 0.3.2 already provides TemplateSink, HtmlTemplate.render_to(sink, values), and HtmlTemplate.render_split(values). No separate templates PR is needed.

Step 2: Add render_parts to LiveView

File: livery/live_view.pony

Add the defaulted method as shown in the API section above. live_view.pony currently only imports use json = "json" -- add use templates = "templates" for the TemplateSink reference in the method signature.

Step 3: Add _RenderSink and _RenderDiff Types

New file: livery/_render_sink.pony

Needs use templates = "templates" for the TemplateSink reference. Contains _RenderSink, _RenderDiff, _FullRender, _SlotDiff, _NoChange as shown in the Internal Architecture section.

Step 4: Update Wire Protocol

File: livery/_wire_protocol.pony

Add encode_render_full() and encode_render_diff() as shown above.

Step 5: Update _Connection for Split Rendering

File: livery/_connection.pony

Add _render_sink field, _try_split_render helper, and update on_open and _maybe_rerender as shown above.

Step 6: No Changes to Component Registry or PageRenderer

Components render to full HTML strings via render(). Component 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 7: Update JS Client

Files: client/src/wire.js, client/src/live-view.js

Changes as shown above.

Step 8: Update Examples

All five examples add render_parts overrides. The examples use unqualified use "templates", so the parameter type is TemplateSink ref (not templates.TemplateSink ref as in the library). The pattern is simple for most:

fun box render_parts(assigns: Assigns box,
  sink: TemplateSink ref): Bool
=>
  try
    _template.render_to(sink, assigns.template_values())?
    true
  else
    false
  end

Todo example needs a shared value preparation helper since it builds items_html from component HTML:

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,
  sink: TemplateSink ref): Bool
=>
  try
    _template.render_to(sink, _prepare_values(assigns))?
    true
  else
    false
  end

Update examples/README.md to mention that examples demonstrate split rendering.

Step 9: Tests

Build and 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.

_RenderSink Tests

Test	Type	Verifies
_TestRenderSinkRoundtrip	PonyCheck	render_to(sink) -> full_html() matches HtmlTemplate.render() for single-variable template with random values. Confirms escaping equivalence.
_TestRenderSinkRoundtripMultiVar	PonyCheck	Same with three variables.
_TestRenderSinkIfCollapse	Example	if block collapses to one dynamic; verify sizes and full_html().
_TestRenderSinkEmptyDynamics	Example	Statics-only template produces empty dynamics.
_TestRenderSinkInterleave	PonyCheck	Random statics/dynamics arrays, verify full_html() matches manual interleave. Uses generated arrays directly (not templates) to test the reconstruction logic independently.

Roundtrip generator: Generate random ascii_printable(0, 50) strings as template variable values. Create an HtmlTemplate with the variables, render both ways, compare. The HtmlTemplate ensures escaping is exercised.

Counterfactual for roundtrip tests: Break the interleaving order in full_html() (e.g., swap indices), verify the assertion fires. Also verify that HTML special characters (<, &, ") in generated values produce different output from a non-escaping template (confirms the test exercises escaping behavior, not just passthrough).

_RenderSink Diff Tests

Test	Type	Verifies
_TestRenderSinkFirstRender	Example	First result() returns _FullRender.
_TestRenderSinkNoDiff	Example	Same dynamics on second render returns _NoChange.
_TestRenderSinkPartialDiff	Example	Changed slots return _SlotDiff with correct indices and values.
_TestRenderSinkAllSlotsDiff	Example	All slots changed returns _SlotDiff (not _FullRender).
_TestRenderSinkStaticsMismatch	Example	Different template instance (different statics content) returns _FullRender.
_TestRenderSinkClear	Example	After clear(), next render returns _FullRender.
_TestRenderSinkAbandon	Example	After abandon(), cached state is preserved (next render diffs against pre-abandon state).
_TestRenderSinkDiffProperty	PonyCheck	Diff contains exactly the indices where values differ.

PonyCheck generator for _TestRenderSinkDiffProperty: Generate an array of N slots (3-10). For each slot, generate a "base" string. Then generate a second array where each slot uses Generators.bool() to decide whether to copy the base value or generate a new random string. Without the bool() control, random strings almost never match (the PonyCheck generator coverage caveat from CLAUDE.md applies), leaving the _NoChange path undertested.

The property asserts: the returned _SlotDiff.changes array contains exactly those indices where base[i] != modified[i], in order. If all match, the result is _NoChange.

Counterfactual for _TestRenderSinkNoDiff: Change one value between updates, verify _SlotDiff instead of _NoChange.

PonyCheck counterfactual caveat: When checking counterfactuals on property tests, verify the generator actually covers the relevant branch before concluding an assertion is weak. A passing counterfactual might mean the generator rarely produces values reaching the broken branch.

Wire Protocol Tests

Test	Type	Verifies
_TestEncodeRenderFull	Example	Correct JSON structure with "t":"render_full", "s" array, "d" array.
_TestEncodeRenderDiff	Example	Correct JSON with "t":"render_diff", "d" object with string keys.
_TestEncodeRenderDiffEmpty	Example	Empty changes produce empty "d" object.

LiveView Default Test

Test	Type	Verifies
_TestLiveViewRenderPartsDefault	Example	Default implementation returns false.

JS Client Tests

Wire tests (client/test/wire.test.js):

• Decode render_full -- correct structure with statics and dynamics
• Decode render_diff -- correct structure with dynamics object
• Legacy render still works -- regression test
• Empty dynamics in render_full
• Multiple changed slots in render_diff

LiveView tests (client/test/live-view.test.js):

• render_full renders HTML into target
• render_diff patches only changed dynamics
• render_diff before render_full is silently ignored
• Reconnect resets split state (new render_full required)
• Legacy render works and clears split state
• SSR pre-rendered content + split rendering transition
• Out-of-bounds diff indices are ignored

Step 10: Update Documentation

CLAUDE.md:

• Add render_parts() to the Public API section (on LiveView)
• Add _RenderSink, _RenderDiff, _FullRender, _SlotDiff, _NoChange to Internals
• Add render_full / render_diff to Wire Protocol
• Add _render_sink.pony to File Layout

Package docstring (livery/livery.pony): Add a section on split rendering explaining the opt-in mechanism, when to use it, and the typical render_parts implementation pattern.

Examples README (examples/README.md): Update descriptions to mention split rendering.

Implementation Order

Step 1: Update corral.json to templates 0.3.2
  |
Steps 2-4 can be developed in parallel:
  Step 2: LiveView trait addition
  Step 3: _RenderSink (new file)
  Step 4: Wire protocol encoding
  |
Step 5: _Connection integration (depends on 2-4)
  |
Step 6: Verify no changes needed (components, PageRenderer)
Step 7: JS client changes (can parallel with Step 5)
  |
Steps 8-10: Examples, tests, documentation

Steps 2-4 have no compile-time dependencies on each other. Step 5 integrates them all into _Connection. The JS client work (Step 7) can proceed in parallel with Step 5. Tests (Step 9) span the full process -- each step's tests are written alongside the step, with the full suite run at the end.

Files Changed

New files:

• livery/_render_sink.pony -- _RenderSink, _RenderDiff, _FullRender, _SlotDiff, _NoChange

Modified files:

• corral.json -- templates 0.3.2
• livery/live_view.pony -- add render_parts(), add use templates = "templates"
• livery/_wire_protocol.pony -- encode_render_full(), encode_render_diff()
• livery/_connection.pony -- _render_sink field, _try_split_render helper, dual render path
• livery/_test.pony -- all new server tests
• livery/livery.pony -- package docstring update
• client/src/wire.js -- decode new message types
• client/src/live-view.js -- split state, _applyHtml, _assembleHtml, 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 -- update descriptions
• CLAUDE.md -- update public API, internals, wire protocol, file layout

Unchanged:

• livery/assigns.pony
• livery/socket.pony
• livery/component_socket.pony
• livery/factory.pony
• livery/page_renderer.pony
• livery/info_receiver.pony
• livery/_null_info_receiver.pony
• livery/pub_sub.pony
• livery/router.pony
• livery/listener.pony
• livery/_component_registry.pony
• livery/_unreachable.pony
• livery/live_component.pony
• client/src/socket.js
• client/src/events.js
• client/src/index.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.

[SeanTAllen]

implemented by #31