design(sdui): adaptive questionnaire flows via server-side transition logic

[roblevintennis]

Problem

The current model handles finite, pre-authored branching well — the account-setup wizard fixture demonstrates this. But it hits a ceiling with adaptive questionnaire UIs: multi-step flows where each screen's questions depend on accumulated runtime answers, and entire sections are skipped based on prior responses (health intake forms, insurance applications, onboarding surveys).

The core issue: every possible screen state must be pre-authored. There is no way for a node array to express conditional visibility or branches that depend on values the user has not yet entered. For a questionnaire with N decision points this creates an unmanageable fixture explosion.

Decision: server-side transition logic (stateless renderer)

The renderer stays fully stateless. The consumer owns answer accumulation and next-screen computation. The integration contract is:

User answers question(s) on current screen
  → on_change fires with { id, value } for each input
  → consumer accumulates answers: { smoker: true, age: 45, hasDiabetes: false, ... }
  → user clicks Next/Submit action
  → consumer POSTs accumulated answers to server or LLM endpoint
  → server/LLM returns next AgNode[] based on answers
  → consumer calls setNodes(nextNodes)
  → renderer displays next screen

This is consistent with the existing action dispatch contract in SPECIFICATION.md section 5. No renderer changes are required for transition logic — only the on_change payload standardization tracked in the sub-issue below.

Why not the alternatives:

• showIf / conditional fields (client-side): adds expression evaluation to the renderer, violates the stateless boundary, still explodes with complex answer combinations
• Richer payloads alone: necessary prerequisite but not sufficient — the consumer still needs something to compute the next screen
• AgFlow primitive: significant scope increase and premature abstraction before real questionnaire usage data exists

Existing demos are not affected

The current fixture-driven demos (contact-form, login-form, account-setup, pricing-card) demonstrate linear and finite-branch flows and remain unchanged. The questionnaire work is additive.

Sub-issues

• feat(sdui): standardize on_change payload to { id, value } across all form input components #461 — Standardize on_change payload to { id, value } across all form input components (renderer/codegen engineering)
• feat(sdui): add adaptive questionnaire reference demo and LLM prompt example #462 — Add adaptive questionnaire reference demo and update SYSTEM_PROMPT.md (demo/docs)

Out of scope

The skipComponents list (Combobox, Menu, Pagination, Sidebar, Slider, Toast and others) is tracked in #375 and #460. Not in scope here.

Related

• SPECIFICATION.md sections 4 (Stateful Component Policy) and 5 (Action Dispatch Semantics)
• #375, #460 — stateful component support
• v2/sdui/demo-llm/ — natural host for the questionnaire reference implementation

[roblevintennis]

Implemented in: #466 and #464 and #462