[API] Return list[StepResult] from both loop steps (#562)

[spaingnv]

Closes #562.

What changed

The contract is two files:

• flashdreams/flashdreams/api_v2/loop.py — ILoop.step (and IUILoop.step)
  return list[StepResult]. A model list is one entry per channel, or []
  when the step produced no presentable output (Support multi devices postprocessing in Interactive Drive #605 already defined that).
  A UI list is one frame to present, or [] to present nothing this tick
  (what used to be None).
• flashdreams/flashdreams/runtime_v2/session_runner.py — the UI thread
  consumes that list: skip window.write on [], write [0] on one
  result, TypeError on more than one. window.write still takes a
  single frame.

Everything else is rewiring and docs: Blit / SlangPy / ImGui wrap the frame
they already produced, tests that treated a UI step return as a bare
StepResult unwrap [0], and the api_v2 / runtime_v2 READMEs describe
the list.

Why

The three-way type (StepResult | None | list[StepResult]) was one
signature covering two contracts. Unifying the annotation without the UI
0-or-1 rule would hide that window.write is one present.

Not in this PR

• Writing every UI list element. window.write is still one present per tick.
• Flattening ILoop or merging the two threads.
• Changing model empty-list behavior. Support multi devices postprocessing in Interactive Drive #605 already defined that.

Validation

• uv run --no-sync pytest flashdreams/test_v2 apps/cam2v/tests/test_application.py apps/crazy_robotaxi/tests/test_ui.py -m ci_cpu — 262 passed, 11 skipped.
• uv run --no-sync pytest apps/cam2v/tests/test_ui_cuda.py -m ci_gpu — 1 passed.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[spaingnv]

/ok to test 8168208

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the prior UI element-validation defect is fixed and no new actionable issue was introduced since the previous review.

Summary

This PR unifies model-loop and UI-loop step returns under list[StepResult] while retaining the UI loop’s zero-or-one-result constraint.

• Updates the public loop interfaces and documentation to describe the unified return type.
• Wraps built-in UI-loop frames in one-element lists and uses empty lists when nothing should be presented.
• Validates UI-loop result containers, element types, and cardinality before writing the single frame to the client window.
• Updates application and runtime tests for the new contract, including invalid-element and multiple-result cases.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    UI[IUILoop.step] --> Results["list[StepResult]"]
    Results --> Check{Valid zero-or-one list?}
    Check -- No --> Error[Raise TypeError]
    Check -- Empty --> Skip[Skip window.write]
    Check -- One result --> Write["window.write(results[0])"]

Loading

_{Reviews (3) · Last reviewed commit: "Silence ty on the UI loop junk-element t..."}

[spaingnv]

/ok to test c28f341

[spaingnv]

/ok to test c91b837