Linux native SDK and WebGPU support for AppScene's selectable Headless platform

[danwalmsley]

Goal

Build and install a pinned Linux AppScene/WebScene SDK so native applications can be launched, rendered, interacted with and verified without a desktop session. This issue records the requested architecture and tracks the WebScene portion of the paired implementation; opening it is not an implementation or validation claim.

Architectural decision

Headless is an AppScene platform, selectable alongside the existing windowing-platform implementations (some integration code may retain the legacy Foco name). It must not be a separate private application host, a WebScene-only test harness pretending to be an AppScene application, or a retained JavaScript runtime used to drive native applications.

Separate platform selection from graphics backend selection. AppScene owns the headless host, input dispatch, scheduling, platform services and offscreen composition. WebScene owns native document/style/layout APIs and the reusable WebGPU implementation, including Linux-specific graphics integration where required. Reuse the same public document/composition/lifetime contracts used by the windowed platforms.

Implementation scope

• Audit current main and recent macOS/Windows WebGPU work (Native WebGPU on macOS and Windows with AOT application and media support #43), native SDK work (Add native documents, compiled UI, and relocatable WebScene SDK #64), and Linux handover [Handover] Linux WebGPU/WebGL parity with Chrome-inspired GPU composition #46 before changing shared code; preserve unrelated changes and existing platform behavior.
• Build/export the native Linux SDK and compiler with explicit pinned source/toolchain/dependency revisions and relocatable installed-package targets. Native consumers must not require Runtime/V8.
• Extend the pinned Dawn/Vulkan path and required Linux offscreen image/composition integration. Keep backend/adapter identity and software-versus-hardware status observable; never silently substitute a CPU renderer and call it GPU qualification.
• Preserve bounded immutable image ownership, producer/consumer synchronization, retained images during resize and safe retirement. Progress GPU completion while headless, hidden or without animation frames. Do not add routine CPU pixel transport or per-frame queue-idle waits. Explicit screenshot/readback operations are allowed and must be accounted separately.
• Pair this with an AppScene PR adding the selectable Headless platform: native pointer/keyboard/text/wheel input, resize/DPR/theme controls, host-thread task dispatch, offscreen output/capture and clean shutdown. Automation must use real native input/document APIs, not JavaScript evaluation.
• Provide reproducible Linux installed-SDK consumer builds and automation that exercises UI interaction, layout/render output and background completion without DISPLAY/Wayland/Xvfb requirements for the headless platform.

Native application profile

Keep the developer-guide architecture: compile HTML and templates into C++ at build time, explicitly select CSS_BACKEND shared and link WebScene::SharedCSS, use C++20 application modules and AppScene::Native, and do not introduce runtime HTML parsing, application scripts or V8 for native apps. Existing hybrid applications remain separately identified.

Validation and delivery

• Test real installed-SDK applications, not only source-tree probes: input/shortcuts, resize at multiple dimensions/DPRs, themes, screenshot/layout assertions, background work, cancellation and repeated shutdown.
• Run actual WebGPU rendering/readback assertions on a recorded Linux adapter. Mark software Vulkan functional coverage separately from physical hardware/desktop qualification; unavailable hardware is not a pass.
• Check packaged ELF dependencies/RPATHs, relocation and native-only link inputs; retain macOS/Windows regression coverage.
• Submit linked WebScene and AppScene PRs with exact revisions, commands, test reports, artifacts and remaining gaps. Do not close [Handover] Linux WebGPU/WebGL parity with Chrome-inspired GPU composition #46 or the GPU epic based solely on a headless milestone.

Related: #46 (broader Linux desktop GPU parity), #24 and #33 (ownership and completion without RAF), #43 and #64 (implementation references).

[danwalmsley]

Implementation is submitted in the paired draft PRs:

• WebScene Add native Linux SDK and bounded offscreen Vulkan WebGPU surfaces #68: native Linux SDK, offscreen Vulkan surfaces, retained image ownership and GPU completion, installed-package tests.
• SceneTech/AppScene#56: selectable APPSCENE_PLATFORM=headless, native event loop/input/automation/captures, SDK producer and qualification workflow.

This session extended both PRs rather than creating duplicate implementation branches. WebScene contribution: a549598048d576ea218a3bc7c7c13ddf6a70178d and 531ee5d1a2a71abc3c9389f9bc4f826ad36f98d5. AppScene contribution: 3e924d604620b2799c507b2a3ffd7bdbf8c5e2df; its workflow pins the paired WebScene revision.

13/13 Python transport-client regression tests passed locally, including failing-baseline evidence for timeout/handshake defects. Full installed native application/GPU/capture/ELF qualification remains a release gate; the drafts and this issue must not be described as a completed SDK release based only on those unit tests.