fix(desktop): make generated HTML previews truthful and directly openable
- Dominant language
- TypeScript
- Stars
- 5.4k
- Forks
- 502
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 715
Description
## Problem
A real H5 workflow exposed several misleading or unreliable assumptions in the local preview handoff:
- `file://` navigation is rejected by the embedded Browser because it requires an HTTP origin. This is an intentional security boundary, not a readiness signal.
- An ad-hoc `python3 -m http.server` process was reported as `running`, while a subsequent request to `127.0.0.1` failed with connection refused.
- The shell process environment and the Desktop Browser do not necessarily share files, localhost networking, or process lifetime.
- The shell `open` command is not a reliable GUI handoff in a sandboxed runtime.
- The agent could therefore say “started”, “ready”, or “opened” before the user had a usable page.
The harness self-evaluation identified the underlying product gaps: incomplete capability discovery, untrusted background-task status, missing endpoint health evidence, weak process observability, and no reliable local artifact handoff.
## Resolution
Maka Desktop must provide one supported, truthful handoff for generated HTML: the HTML Artifact path. The supported flow is:
`Write HTML → register HTML Artifact → show it in Generated Files → Open → materialize through validated main-process IPC → launch with the operating system default application`.
This flow must not require `file://` navigation in the embedded Browser, an ad-hoc localhost server, or a shell `open` command. It also needs an actionable Finder fallback when an HTML preview cannot be read.
The generic shell/browser sandbox limitations remain intentional boundaries. The product must not claim that an arbitrary background process is a healthy preview endpoint merely because its process state is `running`; instead, it should use the Artifact handoff or report the unsupported capability clearly.
## Scope
Maka Desktop Artifact UI, Artifact visibility policy, and the existing validated Artifact IPC path. This issue records the harness self-evaluation symptoms and their product-facing mitigation; it does not introduce a generic process supervisor, weaken the `file://` security policy, or make Shell and Desktop Browser share a network sandbox.
## Acceptance criteria
1. Directly generated HTML files are registered as HTML Artifacts and are visible in the Generated Files panel.
2. The HTML Artifact has an explicit `Open` action in that panel.
3. The action materializes the file through the existing path validation boundary and launches HTML with the operating system default application; it does not rely on localhost or embedded `file://` navigation.
4. Unreadable HTML previews retain a clear Finder fallback through Artifact IPC.
5. User-visible copy does not call an unverified background process `ready` or an unconfirmed browser handoff `opened`; unsupported ad-hoc preview paths remain clearly reported as unsupported.
6. Focused regression tests cover Artifact visibility, HTML materialization/default-app launch, and the unreadable-preview fallback.
## Remaining harness/platform gaps
The following findings from the harness self-evaluation are still open and are not implemented by PR #5216. They should be tracked as platform or harness follow-ups rather than treated as missing Desktop Artifact behavior:
- Browser admission does not support `file://`; it requires an HTTP origin.
- Shell and Desktop Browser may not share filesystem visibility, localhost networking, or process lifetime.
- A background task state of `running` does not prove that a server is listening or reachable; the harness needs explicit `spawned`, `listening`, `healthy`, `unreachable`, and `exited` states, plus startup/exit logs and health checks.
- The shell `open` command cannot be assumed to provide a working GUI/default-browser handoff from a sandbox.
- There is no dedicated `desktop_open_file` or `browser_open_local_artifact` capability, nor a platform-managed Artifact preview endpoint.
- Capability discovery does not clearly report URL-scheme, GUI, localhost, and sandbox constraints before an operation is attempted.
- Archived command output is not seamlessly paginated with enough live error/status context for reliable diagnosis.
- The harness lacks a single verified `create preview → open → confirm loaded` operation and a preflight check for GUI/browser/filesystem/network capabilities.
These gaps remain intentionally out of scope for the current Desktop PR. The supported product behavior is the Artifact handoff described above; unsupported ad-hoc localhost or shell-open paths must be reported as unsupported rather than described as ready or opened.
Related: #4267
Contributor guide
Research direction
Start with the Maka Desktop Artifact UI, the Generated Files panel, and the existing validated Artifact IPC path. Trace how generated HTML becomes visible and how unreadable previews reach the Finder fallback, then run or add focused regression tests for visibility, materialization/default-app launch, and fallback behavior. Done means the supported Artifact handoff is truthful and unsupported preview paths are not reported as ready or opened.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- electron, typescript
- Domain
- desktop
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 64/100