[API] Add client file selection on `IClientWindow` by spaingnv · Pull Request #725 · NVIDIA/flashdreams

spaingnv · 2026-10-15T23:10:45Z

Replaces #674 with the same change as one commit on current main, for a clean history.

Summary

Fixes #649: a UI loop calls request_file_selector(request_id, initial_path=None, *, accept=(), max_file_bytes=None, multiple=False), and the result comes back on a later tick as one SelectedFilesUserInputEvent carrying request_id, on the same input stream as keyboard and mouse.
The event has status and files (name + data bytes, no host path). status is ok, cancelled, busy, too_large, disallowed_type, or unavailable. Sizes are clamped to 32 MiB per file, 256 MiB and 256 files per set. Apps do not branch on --mode.
IClientWindow owns the rules and creates every event: every call gets exactly one event unless its session ends first; one picker at a time (a call while one is open is answered busy); results are checked against the request (types, sizes, count, base names); an internal id per picker so late results are dropped; unavailable if a picker is not shown within 30 s, and no deadline once it is shown. Session replacement withdraws an open picker without a result. Windows implement the platform hooks and the abstract _put_user_input_event; the IClientWindow docstring is the full lifecycle.
Native opens a Tk file dialog on a worker thread, so the window keeps presenting. WebRTC shows a non-modal "The app requested a file" prompt; Select… opens the browser's chooser, and the bytes are uploaded with a one-time token that only the connected page receives. MP4 and null answer unavailable.
Demo: imgui-ui-file-picker with Open file (A), Open file (B) and Open files, asking for .bin / .raw. Failed picks show in red with the status name.

Test plan

CPU:

uv run --no-sync pytest -m ci_cpu \
  flashdreams/test_v2/test_selected_files.py \
  flashdreams/test_v2/test_session_runner.py \
  flashdreams/test_v2/test_native_window_client_window.py \
  flashdreams/test_v2/test_webrtc_client_window.py \
  integrations_v2/imgui_ui_demo/imgui_ui_demo/tests/test_imgui_ui_demo.py

Native: Open file (A) → Tk dialog filtered to .bin / .raw. While it is open, A or B shows BUSY. under-32mb.bin → name (N bytes); oversize / wrong type / dismiss → red TOO_LARGE / DISALLOWED_TYPE / CANCELLED. Open files accepts several files. The window keeps presenting while the dialog is open.

uv sync --package flashdreams-imgui-ui-demo --inexact
uv run --no-sync flashdreams-run-v2 imgui-ui-file-picker --mode native-window

WebRTC: same buttons; prompt ("The app requested a file") → Select… → browser chooser (not the GPU host). Same statuses as native. Video keeps playing under the prompt.

uv sync --package flashdreams-imgui-ui-demo --inexact
uv run --no-sync flashdreams-run-v2 imgui-ui-file-picker --mode webrtc --host 127.0.0.1 --port 8080

MP4 / null: no interactive client; they answer unavailable, covered by the CPU tests above.

copy-pr-bot · 2026-10-15T23:10:48Z

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.

greptile-apps · 2026-10-15T23:15:22Z

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no new actionable issues remain.

Summary

Adds client file selection through IClientWindow, with results returned as SelectedFilesUserInputEvent.

UI loops receive checked file results through the normal input stream.
Native windows let users choose files without stopping presentation.
WebRTC viewers can choose files in their browser and send them to the app.
The ImGui demo shows results for three file-picker controls.
Test windows include the new event-queue hook.

Diagram

sequenceDiagram
  participant UI as UI loop
  participant Window as IClientWindow
  participant Picker as Native or browser picker
  UI->>Window: Request file selection
  Window->>Picker: Show chooser
  Picker-->>Window: Status and chosen files
  Window->>Window: Check request limits
  Window-->>UI: SelectedFilesUserInputEvent on a later tick

_{Reviews (11) · Last reviewed commit: "Release pointer lock when the browser pr..." · Reviewed by Greptile}

spaingnv · 2026-10-16T00:29:46Z

/ok to test 77c89cf

spaingnv · 2026-10-16T00:40:34Z

/ok to test f66bcd0

spaingnv · 2026-10-17T00:20:13Z

/ok to test 7a7be4a

ArielG-NV

Design is effectively perfect; minor clean-up suggested.

spaingnv · 2026-10-19T21:36:21Z

/ok to test 231b722

ArielG-NV

Minor changes suggested.

spaingnv · 2026-10-20T00:33:06Z

/ok to test 8fde1264c

copy-pr-bot · 2026-10-20T00:33:09Z

/ok to test 8fde1264c

@spaingnv, there was an error processing your request: E2

See the following link for more information: https://docs.gha-runners.nvidia.com/cpr/e/2/

spaingnv · 2026-10-20T00:33:13Z

/ok to test 8fde126

Signed-off-by: Set Paing <spaing@nvidia.com>

Remove the file-selector locks: IClientWindow and the WebRTC server's upload tokens are each touched by one thread. The native file dialog runs in a child process polled by the UI thread, so a dialog left open when its session ends is closed. Trim the file-selection docstrings. Signed-off-by: Set Paing <spaing@nvidia.com>

The native dialog writes its paths to a temporary file, so a long path list cannot fill a pipe and block the child. The WebRTC page trusts the server's one-selector rule and replaces a finished picker with a new one. Signed-off-by: Set Paing <spaing@nvidia.com>

Signed-off-by: Set Paing <spaing@nvidia.com>

- Run the native Tk dialog on a worker thread instead of a child process. A dialog left open at session end stays until the user closes it; its result is dropped by the selector id, and new requests get BUSY meanwhile. - Drop the 30-second presentation deadline and the browser ack it needed. - Rename _checked_result to _check_file_selection_result, mark request_file_selector and flush_file_selectors @Final, and use Path(name).name for basenames. - Add a delayed "Restart session" button to the file-picker demo. Signed-off-by: Set Paing <spaing@nvidia.com>

Restore main's behavior: input read by a run with no step is dropped. Signed-off-by: Set Paing <spaing@nvidia.com>

request_file_selector takes max_file_bytes, max_total_bytes and max_file_count, defaulting to 1 GiB, 1 GiB and 256, with no hard ceiling. max_file_bytes must not exceed max_total_bytes. The WebRTC server enforces the app's limits on its side and bounds the request body up front. Signed-off-by: Set Paing <spaing@nvidia.com>

spaingnv

Review by @ArielG-NV

max_file_count now decides whether a picker may return several files and defaults to 1. The browser uploads each file as its own raw request, so the server holds every byte it reads to max_file_bytes, max_total_bytes and max_file_count, with no separate allowance for multipart framing. Spell out TOO_LARGE and reword _put_user_input_event. Signed-off-by: Set Paing <spaing@nvidia.com>

spaingnv · 2026-10-20T19:19:41Z

/ok to test a9298e0

spaingnv · 2026-10-20T19:31:04Z

/ok to test 620a016

ArielG-NV

rename/reword

Signed-off-by: Set Paing <spaing@nvidia.com>

spaingnv · 2026-10-20T19:50:34Z

/ok to test 0e3358c

ArielG-NV

PR LGTM, we cannot merge yet for internal reasons.

spaingnv requested a review from a team as a code owner October 15, 2026 23:10

spaingnv requested a review from csyonghe October 15, 2026 23:10

spaingnv mentioned this pull request Oct 15, 2026

[API] Add client file selection on IClientWindow #674

Closed

2 of 4 tasks

spaingnv removed the request for review from csyonghe October 15, 2026 23:12

greptile-apps Bot reviewed Oct 15, 2026

View reviewed changes

Comment thread flashdreams/flashdreams/runtime_v2/serving/web/app.js Outdated

Comment thread flashdreams/flashdreams/runtime_v2/native_window_client_window.py

greptile-apps Bot reviewed Oct 16, 2026

View reviewed changes

Comment thread flashdreams/flashdreams/runtime_v2/native_window_client_window.py Outdated

spaingnv force-pushed the dev/spaing/client-file-selection branch from 62718b8 to 7a7be4a Compare October 17, 2026 00:20

ArielG-NV reviewed Oct 17, 2026

View reviewed changes

spaingnv force-pushed the dev/spaing/client-file-selection branch from 7a7be4a to 231b722 Compare October 19, 2026 21:07

greptile-apps Bot reviewed Oct 19, 2026

View reviewed changes

Comment thread flashdreams/flashdreams/api_v2/loop.py

ArielG-NV reviewed Oct 19, 2026

View reviewed changes

Comment thread flashdreams/flashdreams/api_v2/client_window.py Outdated

Comment thread flashdreams/flashdreams/api_v2/loop.py Outdated

Comment thread docs/source/documentation/demo_api/api_reference/application.md Outdated

spaingnv added 7 commits October 20, 2026 09:38

feat(api_v2): add client file selection

cfd8c4c

Signed-off-by: Set Paing <spaing@nvidia.com>

docs(api_v2): trim the IClientWindow file-selection notes

ff7d62a

Signed-off-by: Set Paing <spaing@nvidia.com>

refactor(api_v2): drop the file-result carryover in _finish_run

02c3a40

Restore main's behavior: input read by a run with no step is dropped. Signed-off-by: Set Paing <spaing@nvidia.com>

spaingnv commented Oct 20, 2026

View reviewed changes

spaingnv force-pushed the dev/spaing/client-file-selection branch from 8fde126 to 90be5df Compare October 20, 2026 18:28

greptile-apps Bot reviewed Oct 20, 2026

View reviewed changes

Comment thread flashdreams/flashdreams/runtime_v2/serving/web/app.js

Comment thread flashdreams/flashdreams/runtime_v2/native_window_client_window.py

spaingnv force-pushed the dev/spaing/client-file-selection branch from 90be5df to a9298e0 Compare October 20, 2026 19:19

greptile-apps Bot reviewed Oct 20, 2026

View reviewed changes

Comment thread flashdreams/flashdreams/runtime_v2/serving/web/app.js

ArielG-NV reviewed Oct 20, 2026

View reviewed changes

Comment thread flashdreams/flashdreams/api_v2/client_window.py Outdated

Comment thread flashdreams/flashdreams/runtime_v2/serving/webrtc_server.py Outdated

Comment thread flashdreams/flashdreams/runtime_v2/serving/webrtc_server.py Outdated

Release pointer lock when the browser prompt opens

0e3358c

Signed-off-by: Set Paing <spaing@nvidia.com>

spaingnv force-pushed the dev/spaing/client-file-selection branch from 620a016 to 0e3358c Compare October 20, 2026 19:50

ArielG-NV reviewed Oct 20, 2026

View reviewed changes

Conversation

spaingnv commented Oct 15, 2026

Summary

Test plan

Uh oh!

copy-pr-bot Bot commented Oct 15, 2026

Uh oh!

greptile-apps Bot commented Oct 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 5/5

Summary

Diagram

Uh oh!

Uh oh!

Uh oh!

spaingnv commented Oct 16, 2026

Uh oh!

Uh oh!

spaingnv commented Oct 16, 2026

Uh oh!

spaingnv commented Oct 17, 2026

Uh oh!

ArielG-NV left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

spaingnv commented Oct 19, 2026

Uh oh!

ArielG-NV left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

spaingnv commented Oct 20, 2026

Uh oh!

copy-pr-bot Bot commented Oct 20, 2026

Uh oh!

spaingnv commented Oct 20, 2026

Uh oh!

spaingnv left a comment • edited by ArielG-NV Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

spaingnv commented Oct 20, 2026

Uh oh!

Uh oh!

spaingnv commented Oct 20, 2026

Uh oh!

ArielG-NV left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

spaingnv commented Oct 20, 2026

Uh oh!

ArielG-NV left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

greptile-apps Bot commented Oct 15, 2026 •

edited

Loading

spaingnv left a comment •

edited by ArielG-NV

Loading

ArielG-NV left a comment •

edited

Loading