Phase 6: Static/Dynamic Splitting — Refined Implementation Plan

[SeanTAllen]

Design: #3
Predecessor: #28

This is the refined implementation plan for Phase 6 of the livery design, replacing the preliminary plan in Discussion #28. All four open questions from #28 are resolved. The plan includes concrete Pony code with capability issues addressed, a performance analysis, and a complete test plan.

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.

Resolved Open Questions

Q1: Adding render_parts() to the LiveView Trait

Decision: Add fun box render_parts(assigns: Assigns box): (RenderParts | None) => None as a defaulted method on LiveView.

This is backward compatible -- existing views compile and work unchanged. The design document's statement that "the LiveView trait stays the same" is interpreted as "existing views don't break," not "the trait gains zero new methods." The handle_info precedent supports this: it was added as a defaulted no-op method, same pattern.

Alternatives considered and rejected:

• Separate SplitLiveView trait: Pony cannot downcast from LiveView ref to a subtype, so _Connection couldn't call render_parts on a LiveView ref it already holds.
• Socket.register_split_template() in mount: Mixes rendering concerns into lifecycle setup.

Q2: Partial vs Non-Partial

Decision: Non-partial, returning (RenderParts | None). None encodes both "not supported" and "rendering failed." The framework's response to both is identical: fall back to render(). Making it partial would require two error paths for no benefit. The inconsistency with render() being partial is acceptable because the semantics differ -- render() is the single source of HTML and must distinguish success from failure, while render_parts() is an optional optimization with an automatic fallback.

Q3: String Comparison Performance

Decision: Accept element-wise string comparison for V1. The comparison cost is marginal relative to the render cost itself (template evaluation, escaping, string building). For typical payloads, the comparison is negligible -- counter: 1 slot, 1-4 bytes; form: 7 slots, each 0-50 bytes; todo with 100 items: 1 large slot but comparison adds roughly 10-20% overhead to the render cycle, which is acceptable. The correct long-term optimization (assign-level dependency tracking to skip rendering entirely for unchanged slots) requires template static analysis and is deferred.

Alternatives evaluated and rejected for V1:

• Hashing: Adds hashing cost on every render. For small strings (< 100 bytes), hashing is slower than direct comparison. No net benefit for typical payloads.
• Checksums (CRC32/xxHash): Same analysis as hashing.

Q4: Render Method Duplication

Decision: The _prepare_values helper pattern is sufficient. Views with derived template values (e.g., todo building items_html from component HTML) extract value preparation into a shared helper used by both render() and render_parts(). Both methods still exist, but the duplicated logic is minimal -- each is a thin wrapper around the shared helper.

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 (belongs in the templates repo).
4. Reconnection resets state. New _Connection actor = fresh _RenderState. 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	Statics size	Full render	render_full (first)	render_diff (subsequent)	Savings
Counter	~150 bytes	~170 bytes	~200 bytes	~15 bytes	Break-even after 2 renders
Form	~500 bytes	~530 bytes	~550 bytes	~30 bytes (1 field change)	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 the current full-HTML message due to the statics array overhead. Break-even occurs after just 2 renders for any view. Split rendering wins for any view that gets more than 2 renders per connection, which is every interactive view.

Memory Per Connection

_RenderState stores: one _statics pointer (8 bytes), one _prev_dynamics array of N String val references (~8N bytes + string data). Counter: trivial. Form (7 slots): ~56 bytes of pointers. A 50-slot template: ~400 bytes of pointers. The dynamics array from render_split is val and assigned directly to _prev_dynamics -- no copying. The old array becomes garbage via standard Pony GC.

CPU Cost of Diff Computation

• Statics identity comparison (is): O(1) single pointer comparison. Works because HtmlTemplate caches statics as a val field -- same template instance, same reference. Two different HtmlTemplate instances from identical source have different statics allocations -- is returns false, triggering a harmless full render. No false negative risk. The val reference survives GC compaction (Pony GC uses identity tags that are stable).
• Dynamic element-wise string comparison: O(N * M) where N = slots, M = average string length. For common cases (most slots unchanged), size mismatch on the String val provides an early-out before byte comparison.

full_html() Allocation

Pre-allocates a result string to total size (one allocation + N+1 copies). Called on every non-_NoChange render to update _last_html for error recovery. Not called on _NoChange since _last_html is already current.

JSON Encoding Overhead

render_diff string keys add ~2 bytes per changed slot (quotes). Negligible for 1-3 changed slots. render_full JSON escaping adds ~5-10% to statics size -- paid once per connection. json.JsonArray.push() is a persistent vector O(log N) per push; for N < 100, immaterial.

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:

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. HtmlTemplate is class val -- fields are immutable after construction -- so statics must be computed eagerly in the constructor, not lazily cached. The cost is one walk of the _parts tree at parse time, O(template size), negligible compared to parsing.

The implementation is a new _render_parts_split that walks _parts the same way _render_parts does, using _HtmlContextTracker for escaping context:

• _Literal text: feed tracker (for context tracking), skip collection (pre-computed in statics)
• Dynamic nodes (_PropNode, _Pipe): evaluate expression with escaping via tracker context, append result to dynamics array
• Control flow (_If, _IfNot, _Loop, _Block): render entire block to a single string using existing _render_parts recursion, add as one dynamic slot. Feed the rendered string through the tracker so subsequent literal/dynamic nodes get correct escaping context.
• After the loop, the statics array is the pre-cached _statics; only the dynamics array is newly built.

If two {{ }} blocks have no text between them, the pre-computed statics array contains an empty string 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 (is)
• Counterfactual: break reconstruction assertion, verify it fires

Step 2: Update Livery's Templates Dependency

Update corral.json to templates 0.4.0. Run make clean before rebuilding -- when a dependency drops or renames files between versions, corral fetch may leave stale files from the old checkout in _corral/.

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.
    """
    let s = statics
    let d = dynamics
    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

Capability note: The full_html() method has a box receiver (default for fun on a val class). Inside the recover val block, this is not sendable, so statics and dynamics fields cannot be accessed directly. The fields are read into local val variables (s and d) before the recover block. Both are Array[String val] val (sendable), so the locals are accessible inside recover.

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

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 every time.

  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 cannot 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:

type _RenderDiff is (_FullRender | _SlotDiff | _NoChange)

class val _FullRender
  """First render or template change -- send statics + all dynamics."""
  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'

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

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

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


class _RenderState
  """
  Per-connection state for computing diffs between successive split renders.

  Tracks the previous statics reference and dynamics array. On each update,
  compares the new render output against the previous state and returns the
  minimal diff needed.
  """
  var _statics: (Array[String val] val | None) = None
  var _prev_dynamics: (Array[String val] val | None) = None

  fun ref update(parts: RenderParts): _RenderDiff =>
    let new_statics = parts.statics
    let new_dynamics = parts.dynamics

    // Read previous state before overwriting
    let prev_statics = _statics
    let prev_dynamics = _prev_dynamics

    // Update stored state
    _statics = new_statics
    _prev_dynamics = new_dynamics

    // First render or template change
    match prev_statics
    | let prev_s: Array[String val] val =>
      if not (prev_s is new_statics) then
        return _FullRender(new_statics, new_dynamics)
      end
    | None =>
      return _FullRender(new_statics, new_dynamics)
    end

    // Size mismatch (defensive)
    match prev_dynamics
    | let prev_d: Array[String val] val =>
      if prev_d.size() != new_dynamics.size() then
        return _FullRender(new_statics, new_dynamics)
      end
      // Element-wise comparison
      let changes: Array[(USize, String val)] val = recover val
        let c = Array[(USize, String val)]
        var i: USize = 0
        try
          while i < prev_d.size() do
            if prev_d(i)? != new_dynamics(i)? then
              c.push((i, new_dynamics(i)?))
            end
            i = i + 1
          end
        else
          _Unreachable()
        end
        c
      end
      if changes.size() == 0 then
        _NoChange
      else
        _SlotDiff(changes)
      end
    | None =>
      _FullRender(new_statics, new_dynamics)
    end

  fun ref clear() =>
    """
    Reset tracked state. Used when a view transitions from split rendering
    back to full-HTML rendering, so stale state doesn't persist.
    """
    _statics = None
    _prev_dynamics = None

Capability note: Inside the recover val block, prev_d and new_dynamics are both Array[String val] val (sendable), so they are accessible. The changes array is built inside recover and becomes val on exit.

Step 6: Update Wire Protocol

File: livery/_wire_protocol.pony

Two new encoding functions alongside the existing encode_render:

fun encode_render_full(statics: Array[String val] val,
  dynamics: Array[String val] 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)] val): String val
=>
  """
  Encode a partial update: only changed dynamic slot values.
  Uses 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"}}

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. The render_diff string-keys-on-object format matches Phoenix LiveView's approach.

Step 7: Update _Connection for Split Rendering

File: livery/_connection.pony

Add let _render_state: _RenderState ref = _RenderState as a field.

Both on_open and _maybe_rerender get a dual render path. The initial render in on_open tries render_parts first:

match view.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 = 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

The _maybe_rerender method follows the same pattern, with one addition -- when render_parts returns None after previously returning RenderParts, the server calls _render_state.clear() to discard stale state:

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 =>
      _render_state.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()

Fallback transition: When the server sends a plain render message (not render_full or render_diff), the client clears its split state. This handles the case where a view switches from split to full rendering mid-session.

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

Add two new cases to 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 for the full-HTML fallback path.

Step 10: Update JS Client LiveView

File: client/src/live-view.js

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

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 if (!this._statics || !this._dynamics) break prevents corrupted state.
• Out-of-bounds diff indices are ignored. The bounds check i >= 0 && i < this._dynamics.length prevents malformed messages from corrupting the array.
• Legacy render clears split state. If the server falls back to full-HTML, the client discards stale statics/dynamics.

Step 11: Update Examples

All five examples add render_parts overrides. Views with derived values use the _prepare_values helper pattern.

Counter example (examples/counter/main.pony) -- straightforward override:

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

Todo example (examples/todo/main.pony) -- shared value preparation:

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

The ticker, form, and ssr examples follow the same pattern as counter (direct template override) or todo (shared helper), depending on whether they have derived values.

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

Step 12: 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.

Server Tests (livery/_test.pony)

RenderParts tests:

Test	Type	Verifies
_TestRenderPartsFullHtml	Example	Known statics ["<div>", "</div>"] + dynamics ["42"] produce "<div>42</div>"
_TestRenderPartsEmptyDynamics	Example	Statics ["hello"] + dynamics [] produce "hello"
_TestRenderPartsInterleave	PonyCheck	full_html() matches manual interleave for random inputs

PonyCheck generator for _TestRenderPartsInterleave: Generate a random number of dynamic slots (1-20 via Generators.usize(1, 20)), then for each: generate random static strings and dynamic strings via Generators.ascii_printable(0, 50). Ensure statics.size() == dynamics.size() + 1 by construction (generate N dynamics and N+1 statics).

Counterfactual: break the interleaving order (e.g., swap statics[0] and statics[1]), verify assertion fires.

_RenderState tests:

Test	Type	Verifies
_TestRenderStateFirstRender	Example	First update returns _FullRender
_TestRenderStateNoDiff	Example	Same dynamics returns _NoChange
_TestRenderStatePartialDiff	Example	Changed slots return _SlotDiff with correct indices
_TestRenderStateStaticsChanged	Example	Different statics reference returns _FullRender
_TestRenderStateSizeMismatch	Example	Dynamics size mismatch returns _FullRender
_TestRenderStateClear	Example	After clear(), next update returns _FullRender
_TestRenderStateDiffProperty	PonyCheck	Diff contains exactly the indices where values differ

PonyCheck generator for _TestRenderStateDiffProperty: 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. This ensures both matching and non-matching slots appear regularly -- without the bool() control, random string generation almost never produces matching slots (the generator coverage caveat from CLAUDE.md applies), making 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. If any base vs modified pair differs, it is _SlotDiff.

Counterfactual caveat: When checking counterfactuals on PonyCheck 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 None

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 (clears split state)
• SSR pre-rendered content + split rendering transition
• Out-of-bounds diff indices are ignored

Step 13: Update Documentation

CLAUDE.md:

• Add RenderParts and render_parts() to the Public API section
• Add _RenderState, _RenderDiff, _FullRender, _SlotDiff, _NoChange to Internals
• Add render_full / render_diff to Wire Protocol
• Add render_parts.pony and _render_state.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: Templates library PR (critical path -- separate repo)
  |  release as 0.4.0
Step 2: Update corral.json to templates 0.4.0
  |
Steps 3-6 can be developed in parallel:
  Step 3: RenderParts type (new file)
  Step 4: LiveView trait addition
  Step 5: _RenderState (new file)
  Step 6: Wire protocol encoding
  |
Step 7: _Connection integration (depends on 3-6)
  |
Step 8: Verify no changes needed (components, PageRenderer)
Steps 9-10: JS client changes (can parallel with Step 7)
  |
Steps 11-13: Examples, tests, documentation

Steps 3-6 have no compile-time dependencies on each other and can be written in any order. Step 7 integrates them all into _Connection. The JS client work (Steps 9-10) has no Pony dependency and can proceed in parallel with Step 7. Tests (Step 12) 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_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 field, dual render path in on_open and _maybe_rerender
• 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 -- _statics/_dynamics 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.

Remaining Uncertainties

These are genuinely open questions that need empirical verification during implementation:

1. Templates render_split escaping equivalence. The implementation must produce identical escaping to render(). The _HtmlContextTracker processes HTML text character-by-character so rendered control-flow block output should be handled correctly, but this needs verification -- particularly for nested control flow within loops.

2. Templates library PR acceptance and timeline. This is the critical path dependency. The templates library is in the same GitHub organization, but requires a separate PR, review, and release as 0.4.0.

3. Statics caching mechanism in HtmlTemplate. Statics must be computed eagerly in the constructor since HtmlTemplate is class val. This requires walking _parts at construction time to extract the static skeleton -- the exact implementation depends on the _Part type hierarchy (_Literal, _PropNode, _Pipe, _If, _IfNot, _Loop, _Block), which is internal to the templates library.

Synthesis Rationale

This plan was produced by an ensemble of three agents with different attention focuses (API design, testing strategy, performance), each independently reviewing the predecessor plan (#28) and the current codebase. Key contributions by focus:

API agent: Clean resolution of all four open questions with alternatives-considered reasoning. Identified _RenderState.clear() for fallback transitions that the other agents missed. Caught the full_html() recover-val capability issue.

Tests agent: Generators.bool() per-slot strategy for the _TestRenderStateDiffProperty PonyCheck generator -- without this, random strings almost never match, leaving the _NoChange path undertested. Identified the counterfactual caveat for PonyCheck tests (generator coverage vs. weak assertions).

Performance agent: Concrete bandwidth analysis showing break-even after 2 renders. Memory and CPU cost analysis confirming negligible overhead. Resolved the statics identity comparison reliability question. full_html() pre-allocation pattern.

Emergent from combination: The fallback transition story (server-side _render_state.clear() + client-side clearing on legacy render message) emerged from combining the API agent's clear() method with the tests agent's client-side state clearing observation. The recover val capability analysis was verified from three independent angles.

[SeanTAllen]

Implementation PR: #31