docs(ssr): compatible SSR engines reference

[zeroedin]

Summary

• Adds plans/SSR_ENGINES.md documenting the ssr.render stdin/stdout contract
• Lists golit (recommended) and lit-ssr-wasm as compatible engines with config examples and trade-offs
• Includes comparison table and "Adding a new engine" guide for third-party engine authors
• References competitive analysis at redact golit#22

Context

Came out of evaluating lit-ssr-wasm (Benny Powers) alongside golit. Alloy's per-instance render model is engine-agnostic by design — this doc captures that flexibility so the knowledge isn't lost.

🤖 Generated with Claude Code

[zeroedin]

Review: PR #143 — docs(ssr): compatible SSR engines reference

Scope: New file plans/SSR_ENGINES.md — 132 lines

What this is

Reference doc capturing the ssr.render stdin/stdout contract and listing two compatible engines (golit, lit-ssr-wasm) with config examples, trade-offs, and a guide for third-party engine authors.

Analysis

1. Contract section is clear and correct: stdin fragment in, DSD stdout out, exit 0/non-zero. Matches the per-instance model established in PR #135. The "Adding a new engine" section with expected input/output example is exactly what a third-party author needs.

2. Engine descriptions are honest about trade-offs:

   • golit: recommended, fast cold start, but "own rendering implementation — not the official @lit-labs/ssr"
   • lit-ssr-wasm: official Lit SSR fidelity, but ~350ms cold start per invocation, needs warm process mode

3. Comparison table is fair: Doesn't hide golit's conformance gap or lit-ssr-wasm's cold start cost.

4. Config examples match the spec: All YAML blocks use ssr.render (not the old ssr.build), consistent with PR #135's spec rewrite. The serve sub-config with both HTTP and stdio protocol options matches PLAN.md.

5. The ~35 second estimate is useful: 100 unique instances x 350ms cold start = 35s in one-shot mode. Makes a strong case for the ssr.serve warm-process optimization without being preachy about it.

One note

The doc references zeroedin/golit#22 for competitive analysis. If that issue is public, great. If it's in a private repo, external contributors won't be able to follow the link. Not a blocker either way — the comparison table in this doc is self-contained.

Verdict

LGTM — useful reference doc that captures engine-agnostic design knowledge. Correctly reflects the current spec, doesn't duplicate PLAN.md content, and provides practical config examples.

[zeroedin]

Closing — the SSR spec was simplified in #150 from per-instance stdin/stdout to per-page CLI invocation. The stdin/stdout contract, ssr.render, ssr.serve, and multiple protocol support documented here no longer exist in the spec.

If we add lit-ssr-wasm support in the future, we can write a new reference doc that matches the actual contract at that time.