[API] Add client file selection on IClientWindow

apps/action2v/tests/test_application.py

@@ -22,6 +22,7 @@
 from numpy import uint64
 
 from flashdreams.api_v2.client_window import IClientWindow
+from flashdreams.api_v2.user_input_event import UserInputEvent
 from flashdreams.runtime_v2.session_desc import SessionDesc
 from flashdreams.runtime_v2.session_runner import run_session
 from flashdreams.runtime_v2.step_result import StepResult
@@ -138,6 +139,9 @@ def __init__(self) -> None:
         self.opened = False
         self.cursor_requests: list[tuple[str, bool]] = []
 
+    def _put_user_input_event(self, event: UserInputEvent) -> None:
+        del event
+
     def open(self, session_desc: SessionDesc) -> None:
         del session_desc
         self.opened = True

apps/t2v/t2v/testing.py

@@ -21,6 +21,7 @@
 import torch
 
 from flashdreams.api_v2.client_window import IClientWindow
+from flashdreams.api_v2.user_input_event import UserInputEvent
 from flashdreams.runtime_v2.blit_model_output_to_screen_loop import (
     BlitModelOutputToScreenLoop,
 )
@@ -410,6 +411,9 @@ class _DiscardingClientWindow(IClientWindow):
     def get_user_input_events(self) -> UserInputEvents:
         return UserInputEvents([])
 
+    def _put_user_input_event(self, event: UserInputEvent) -> None:
+        del event
+
     def open(self, session_desc: SessionDesc) -> None:
         del session_desc
 

apps/t2v/tests/test_cli.py

@@ -27,6 +27,7 @@
 from flashdreams.api_v2.client_window import IClientWindow
 from flashdreams.api_v2.loop import IModelLoop
 from flashdreams.api_v2.session import ISession
+from flashdreams.api_v2.user_input_event import UserInputEvent
 from flashdreams.runtime_v2 import cli
 from flashdreams.runtime_v2.application_registry import (
     APPLICATION_ENTRY_POINT_GROUP,
@@ -160,6 +161,9 @@ def __init__(self) -> None:
     def get_user_input_events(self) -> UserInputEvents:
         return UserInputEvents([])
 
+    def _put_user_input_event(self, event: UserInputEvent) -> None:
+        del event
+
     def open(self, session_desc: SessionDesc) -> None:
         self.session_desc = session_desc
 

docs/source/documentation/demo_api/api_reference/application.md

@@ -330,6 +330,70 @@ Request a positive downstream client-window width and height.
 - `TypeError`: The size is not a pair of integers.
 - `ValueError`: Either dimension is not positive.
 
+#### `request_file_selector`
+
+```python
+def request_file_selector(self, request_id: str, initial_path: str | None=None, *, accept: Sequence[str]=(), max_file_bytes: int | None=None, multiple: bool=False) -> None
+```
+
+Ask the client to show a file selector. The call only queues the request; the
+result arrives on a later tick as one `SelectedFilesUserInputEvent` in
+`user_events`, carrying `request_id`. The model loop receives the same event.
+
+Every call gets exactly one event unless its session is replaced or shut down
+first. One selector is open at a time: a call made while one is open, including
+a second call in the same tick, is answered `BUSY`. Use one stable
+`request_id` per control.
+
+Read `status` (`SelectedFilesStatus`) before `files`; `files` is empty unless
+the status is `OK`:
+
+- `OK`: each `SelectedFile` has a base `name` (no host path) and its `data`
+  bytes.
+- `CANCELLED`: the user dismissed the selector.
+- `BUSY`: another selector was open, so this one was not shown.
+- `DISALLOWED_TYPE`: a file did not match `accept` (case-insensitive suffixes).
+- `TOO_LARGE`: a file exceeded `max_file_bytes`, or the set exceeded
+  `MAX_SELECTED_FILE_BATCH_BYTES` (256 MiB) or `MAX_SELECTED_FILE_COUNT` (256).
+- `UNAVAILABLE`: no picker (MP4, null), the picker was not shown within 30
+  seconds, the viewer left, the chooser failed, or a file could not be read.
+
+`accept` checks filename suffixes only, so validate `data` as untrusted input.
+`max_file_bytes` above `MAX_SELECTED_FILE_BYTES` (32 MiB) is clamped.
+`initial_path` is a directory hint for the native Tk dialog and is ignored by
+the browser.
+
+```python
+from flashdreams.runtime_v2.selected_file import SelectedFilesStatus
+from flashdreams.runtime_v2.user_input_event import SelectedFilesUserInputEvent
+
+if imgui.button("Open image"):
+    self.request_file_selector("open-image", accept=(".png",))
+for event in self.user_events.get_events():
+    if not isinstance(event, SelectedFilesUserInputEvent):
+        continue
+    if event.request_id != "open-image":
+        continue
+    if event.status is SelectedFilesStatus.OK:
+        image_bytes = event.files[0].data
+    else:
+        self.state.message = f"No image: {event.status.value}"
+```
+
+**Parameters**
+
+- `request_id`: Names the control that asked; echoed on the result.
+- `initial_path`: Native directory hint; `None` uses the host user's home.
+- `accept`: Filename suffixes such as `.png`. Empty allows any type.
+- `max_file_bytes`: Maximum size of each file, or `None` for the ceiling.
+- `multiple`: Whether the selector may return more than one file.
+
+**Raises**
+
+- `TypeError`: An argument has the wrong type.
+- `ValueError`: `request_id` or `initial_path` is empty, or `accept` /
+  `max_file_bytes` is invalid.
+
 #### `get_or_create_ui_loop_requests`
 
 ```python

flashdreams/flashdreams/api_v2/README.md

@@ -224,7 +224,14 @@ UI control that needs a fresh application session calls
 `request_new_session(session_desc)` with a fully resolved replacement
 description; the runtime cleans the current session and passes that description
 to `ApplicationRunner` unchanged. Remaining timeout and remaining model steps
-still apply to the replacement.
+still apply to the replacement. To let the user pick a client file, call
+`request_file_selector(request_id, ...)` when they ask (for ImGui, when
+`imgui.button(...)` returns `True`), with one stable `request_id` per control.
+The result arrives on a later tick as one `SelectedFilesUserInputEvent`
+carrying that `request_id`; read its `status` before its `files`. One picker
+is open at a time, and a call made while one is open is answered `BUSY`. The
+`request_file_selector` docstring is the full contract: timing, every status,
+size and type limits, and what WebRTC shows.
 
 For SlangPy's smaller retained widget API, subclass `SlangPyUILoop` from
 `flashdreams.runtime_v2.slangpy_ui_loop`. The