Files
pipelines/app/notes/A3-files.md
T

55 lines
2.6 KiB
Markdown

# A3 — artifact files: download and share
## Scope
The selected artifact can be saved or shared as a real file. The external
`Open` and `Copy link` actions stay unchanged; neither is reused as a stand-in
for a file transfer.
## Implementation
- `artifact_transfer.dart` is the platform seam with a web implementation and a
stub. The web file uses `dart:js_interop`/`dart:js_interop_unsafe` only, so the
same source compiles to JavaScript and WebAssembly without `package:web`.
- `artifact_transfer_web.dart` builds a `Blob`/`File` from the fetched bytes with
the recorded name and MIME type, downloads through an anchor created for that
name, and shares through `navigator.share` only when the platform can share
files. It never puts the artifact url or a blob page into the user's hands.
- `artifact_file_controller.dart` fetches bytes through the same
`ArtifactFetch` seam the in-app viewer already uses, so the same-origin
credential policy and HTTP status handling apply. One in-flight transfer at a
time; a second activation is ignored. Cancel stops the action from continuing
and a late result is never reported as a completed transfer.
- The selection sheet exposes `Download` and `Share` beside the existing
actions, with honest states for unsupported sharing (download still works),
missing/malformed name or MIME, fetch failure with its HTTP status, and
cancel. Nothing is silently substituted.
## Evidence
- Focused suite: 123 artifact tests pass; `flutter analyze` clean.
- Browser probe (`tool/artifact_gallery_probe.mjs`, 32 captures, 27 checks) on
both hosts, dark at 2x and 320 logical px:
- Material and Cupertino `Download` hand the host `report.csv`, `text/csv`,
23 exact bytes.
- Material and Cupertino `Share` hand the host a `report.csv`, `text/csv`,
23-byte `File`.
- Existing gallery/viewer checks (recorded rows, duplicate filename, empty vs
unavailable, image in-app, HTTP failure, external artifact never fetched,
320/2x paging) still pass.
## Known limits
- The shared fetch seam has no cancellation token, so Cancel abandons the action
without aborting the HTTP request. The UI never claims the transfer finished.
- OS share sheets and file downloads are web-verified only. Android/iOS
transfer behavior remains unverified until the final build.
- No authenticated production artifact was transferred; the probe uses an
isolated fixture with fixed bytes.
## Manager note
The run reached its Code deadline with this tree complete and verified by the
manager: tests, analysis, browser build and the 27-check probe above. Merged
directly rather than replayed.