Add platform capabilities and comprehensive portability coverage

[MrSeizy]

RadioCLI now models runtime eligibility and individual platform capabilities centrally. Playback, storage, browsing, and keyboard navigation remain usable when a scheduler, desktop helper, terminal application, mixer, inhibitor, or optional AirPlay sender is unavailable. Unsupported operations report the missing prerequisite and preserve failure evidence instead of reporting success.

This single draft PR contains the complete cross-platform initiative on codex/comprehensive-cross-platform-support. It starts at 6d8cc2dc7ef8a02e2bf8a2406800e6f6cbce3ab9 (Release 0.2.3). The owner retains final review, merging, and release publication.

Architecture and behavior

src/platform/ separates host identity, upstream Node requirements, implemented adapters, observed capabilities, and project verification. It centralizes executable discovery, explicit package plans, storage paths and access inspection, desktop and terminal commands, shell boundaries, mpv IPC addressing, loopback networking, public-request policy, and terminal rendering policy. Existing operation owners in player, providers, storage, alarms, agent, and ui consume those decisions.

• Existing macOS launchd, Windows Task Scheduler, and Linux systemd adapters retain their occurrence, retry/fallback, snooze, authentication, and cleanup contracts. Early scheduler dispatch no longer consumes an occurrence. Cleanup failures retain health/ownership evidence; an unverified live Guard record cannot authorize killing a PID. Linux checks for an accessible user manager before offering background scheduling.
• Literal path/argument handling and configured player paths survive terminal and scheduler boundaries. Private control traffic uses direct authenticated IPv4/IPv6 loopback connections even when HTTP proxy variables are set. Process startup and verified terminal/session readiness remain separate results.
• Library writes preserve both the old file and in-memory state on failure. Optional cache, history, presence, metadata, and listening-statistics writes report errors while unrelated playback, navigation, stop, and quit remain usable. Imports, exports, current/legacy paths, settings, and stored schemas remain compatible.
• Unicode-rich rendering remains the baseline. ASCII decoration, limited color, NO_COLOR, C/POSIX locales, dumb/redirected terminals, screen-reader output, and reduced motion are explicit invocation policies that do not rewrite saved preferences. Screen-reader mode disables receiver animation and mouse reporting while preserving keyboard controls.
• Offline mode uses cached directories and saved/imported/direct stations while suppressing directory, location, update, vote, and receiver-discovery requests. Low-bandwidth mode reduces background discovery. Remote audio still needs the external player's network path. Native HTTP(S) proxy opt-in is diagnosed; unsupported SOCKS/ALL_PROXY configurations fail explicitly.
• FreeBSD, OpenBSD, NetBSD, and Termux receive verified package-command plans and appropriate executable/desktop paths. Haiku, illumos/SmartOS, AIX, musl, WSL, and additional CPU routes keep their actual runtime, player, or verification limits. There is no speculative cron/at/Android scheduler substitute.

Doctor reports support.scope=current-installation. It checks prerequisites without pretending to run packed-install/audio acceptance tests. Its conservative installation tier is independent of the reference CI configuration's recorded tier.

Subsystems changed

Area	Main files and contracts
Platform architecture	src/platform/{runtime,support,capabilities,paths,executables,packages,desktop,terminals,shell,launch-command,terminal,network,loopback,ipc,storage}.ts and adapter/decision tests
Playback and networking	src/player/{backend-install,command,command-diagnostics,mpv-ipc-client,player-controller,airplay-discovery}.ts, provider adapters/cache, update checker
Alarm and agent reliability	Scheduler, runner, inhibitor, system volume, Guard/ownership stores, setup verification, terminal launcher, active session, agent launcher/session/headless host
Storage and UI	src/storage/store.ts, CLI diagnostics/setup, App/input/command hooks, adaptive rendering and screen components; failure and keyboard/focus integration tests
CI and packaging	Required native x64/arm64 Node 22/24 matrix, BSD full guests, packed harness, native mpv fixture installer, immutable action pins and retained audit gates
Documentation and visual evidence	README, installation, architecture, design/TUI, reliability, privacy/security, contributing, release packaging, roadmap, new platform/troubleshooting pages, audit/verification reports and terminal captures

Coverage before and after

The previous workflow tested Node 22/24 on one Ubuntu, macOS, and Windows runner each. Pull requests skipped live data, playback, and fresh-install checks. Platform/architecture claims were not tied to a recorded evidence tier.

Target	Result after this change
macOS Intel and Apple Silicon	Native x64/arm64 Node 22/24 jobs; both packed installation modes and real native mpv IPC playback are required. Exact product/kernel versions and remaining desktop/audio limits are recorded.
Ubuntu glibc Linux x64 and arm64	Four native Node/CPU combinations, both packed installation modes, real mpv IPC playback, and separate mpv/ffplay source smoke jobs.
Windows x64 and arm64	Four native Node 22/24 jobs with CPU-checked mpv fixtures passed the complete suite, independent-console TTY tests, and both packed installation modes with real named-pipe playback. References: Windows Server 2025 x64 and Windows 11 Enterprise arm64.
FreeBSD 14.4 x64 / OpenBSD 7.9 x64 / NetBSD 10.1 x64	Full QEMU guest kernels with guest-native Node/mpv passed packed CLI/cache/import/export/MCP and real mpv IPC playback. The supported core route installs a local tarball into fresh projects with --omit=optional. Global registry installs, desktop terminals, physical audio, and new schedulers were not the recorded checks.
Alpine/musl, non-systemd Linux, WSL	Explicit runtime, package, audio/session, and scheduler limits; no blanket promotion from glibc/native tests.
Termux, illumos/SmartOS, AIX, additional CPUs	Implemented bounded paths and runtime diagnostics; device/OS/CPU verification remains experimental where no matching packed/audio evidence exists.
Standard HaikuPorts Node 20, Node below 22, Windows XP, 32-bit macOS, Node 24 Windows x86	Known runtime blocker is diagnosed. No legacy client or fabricated native capability is added.

The 12 required native reference configurations are first-class for their recorded capabilities; the three BSD core routes are supported with the limits above. Other listed routes remain experimental or unsupported as stated.

The full platform guide covers minimum OS/libc requirements, x64/x86/arm64/ARMv7/ppc64 endianness/s390x/riscv64, installation, players, TUI, browser/clipboard, alarms, terminal reopening, system volume, inhibition/wake, AirPlay, execution method, tier, and limits.

Verification

Code checkpoint fd57fda passed all 22 jobs in run 34180703652. Final commit: 7762f937933df43e9101e53657750f2215998062. Final CI: run 34181748384, 22/22 jobs passed on the final commit: 12 required native verification jobs, four Linux playback jobs, two documentation jobs, the guest artifact build, and three BSD guest jobs.

Local native environment: macOS 26.5.2, Darwin 25.5.0, arm64. Node 22.23.2/npm 10.9.8 and Node 24.20.0/npm 11.19.0 were installed separately and used for clean dependency installation and acceptance. Supplementary Node 26.8.1 checks exercised the changed proxy/loopback and terminal paths. Mocked host tests are listed as unit evidence, not native verification.

Commands run on both maintained local runtime lines:

npm ci
npm run check
npm run lint
npm run test
npm run build
npm run smoke:data
npm run smoke:mcp
npm run smoke:playback
npm run pack:check
npm run fresh:check -- --require-mpv
npm run check:package
npm run audit:runtime
npm --prefix apps/docs ci
npm run docs:check
npm run docs:build
npm run audit:docs
node --test scripts/packed-smoke.test-node.mjs scripts/install-smoke-mpv.test-node.mjs

The local and eight macOS/Linux CI suites each passed 1,841 tests with three Windows-only skips. Each Windows Node 22 suite passed 1,828 with 16 platform-specific skips; each Windows Node 24 suite passed 1,826 with 18 skips, including two optional AirPlay source checks whose dependency files were absent. All native Windows PowerShell/console probes ran. The standalone package-harness suite passed 12 tests. No existing test deadline, capacity limit, or assertion was relaxed.

Final-run reference environments:

Execution method	OS and kernel	CPU	Node / npm pairs
GitHub-hosted native OS/CPU VM	macOS 26.6.2 / Darwin 25.6.0	arm64	22.23.2 / 10.9.8
GitHub-hosted native OS/CPU VM	macOS 26.5.2 / Darwin 25.5.0	arm64	24.20.0 / 11.19.0
GitHub-hosted native OS/CPU VM	macOS 15.7.9 / Darwin 24.6.0	x64	22.23.2 / 10.9.8; 24.19.0 / 11.17.0
GitHub-hosted native OS/CPU VMs	Ubuntu 24.04.4 LTS / kernel 6.17.0-1022-azure, glibc	x64 and arm64, each tested	22.23.2 / 10.9.8; 24.20.0 / 11.19.0
GitHub-hosted native OS/CPU VM	Windows Server 2025 Datacenter / 10.0.26100	x64	22.23.2 / 10.9.8; 24.19.0 / 11.17.0
GitHub-hosted native OS/CPU VM	Windows 11 Enterprise / 10.0.26200	arm64	22.23.2 / 10.9.8; 24.20.0 / 11.19.0
Same-CPU full QEMU guest	FreeBSD 14.4-RELEASE	x64	22.23.2 / 11.19.1
Same-CPU full QEMU guest	OpenBSD 7.9	x64	22.23.2 / 10.9.8
Same-CPU full QEMU guest	NetBSD 10.1	x64	22.23.0 / 10.9.8

The final run selected macOS 26.5.2 for its arm64 Node 24 job; the earlier code checkpoint selected 26.6.2. The committed verification report retains that checkpoint's exact evidence, and this table records the final run.

Final commit tarball SHA-256 values:

Build and execution	SHA-256
macOS/Linux CI; the Linux artifact also executed in all three BSD guests; both local Node 22/24 packed runs matched	50b0a334d094b023eb19429c7163c58394d5b0de5ec5008f9feb35a4101a86c3
Windows x64 and arm64	Four native Node 22/24 jobs with CPU-checked mpv fixtures passed the complete suite, independent-console TTY tests, and both packed installation modes with real named-pipe playback. References: Windows Server 2025 x64 and Windows 11 Enterprise arm64.

Each native target used the same target tarball for normal and --omit=optional acceptance. The run's packed-* and playback-* artifacts retain structured results; the portability-package artifact retains the tarball executed in BSD, whose guest logs contain the structured packed_smoke records.

The packed harness uses the installed tarball, an isolated data home, paths with spaces, non-ASCII characters, and literal #/%, offline cache hits and misses, direct URLs, library import/export, the generated npm wrapper, and MCP stdio/status with 31 tools. An offline fetch guard catches accidental live requests. Real mpv decodes a local WAV and verifies IPC readiness, volume, pause, resume, and stop using null audio. Normal and --omit=optional installs have separate evidence records. Null audio does not establish audible hardware output.

BSD jobs execute guest-native Node and mpv in same-CPU full guest kernels. The JavaScript package is built on Linux and then installed/executed in each BSD guest; compilation itself is not runtime evidence. NetBSD's minimal image needs the matching official X11 base set for the media package's shared libraries; CI verifies that set's pinned SHA-512 before extraction.

Visual evidence

The first commit captured 578 deterministic Ink snapshots before rendering changes: full/compact/micro screens at 100×30, 50×16, and 24×8, all full-size receivers, representative smaller receivers, ASCII/Unicode, and focused color fixtures.

All 335 Unicode/ANSI captures remain unchanged. Of 243 ASCII captures, 160 intentionally replace remaining decorative Unicode (bars, bullets, ellipses and receiver glyphs), while 83 are unchanged. Station names and metadata retain their characters. Representative before/after terminal captures and the complete snapshot fixture are linked below. These are renderer captures, not screenshots of another platform's terminal application.

Rendering and keyboard tests retain their original assertions, dimensions, and timeouts. Cleanup removes mounted Ink views and host terminal-size subprocesses; all 144 paired screen frames remain identical. A per-test footer-layout cache delegates every distinct input to the real function; all 124 paired journey frames remain identical. Polling tests assert that the active clock actually polls. The 500-alarm storage test retains its capacity limit and original deadline; timezone canonicalization performs one native validation per value instead of two.

Evidence: platform guide, audit, verification record, before/after terminal captures, and complete snapshot fixture.

Dependencies, security, and compatibility

No dependency versions, lockfiles, TypeScript strictness, lint/export checks, audit scripts, or existing security gates were weakened. There are no new runtime dependencies, persisted-schema changes, lifecycle system-package installations, external tap changes, publications, or releases. Required-runtime and documentation audit gates pass; normal installs retain the original two low-severity optional-tree advisories.

All CI actions use immutable full commit pins and read-only repository permissions. macOS/Windows mpv fixtures use fixed official release assets, pinned SHA-256 values, and native CPU-header checks. Linux/BSD catalogs and the VM provider's separately supplied maintained images remain documented external dependencies. Proxy credentials and local control tokens are excluded from diagnostics and terminal handoff payloads. TLS verification remains enabled.

Existing current/legacy library paths and setting defaults are preserved; no migration is necessary. Optional AirPlay remains experimental and macOS-only. A successful normal package install does not prove that its optional native sender loads or connects to a receiver.

Risks and remaining experimental work

The principal remaining risk is desktop/session policy: actual terminal applications, automation consent, scheduler registration and delivery, system mixers, sleep/wake behavior, physical audio devices, and screen-reader applications require evidence beyond unit mocks, fixed Ink captures, and null audio. Runner results apply to their exact OS/CPU/Node profiles, not every Windows desktop edition, older macOS version, Linux distribution, or WSL setup.

Termux devices, musl and less common CPUs, illumos/SmartOS, and AIX retain native verification gaps. Standard HaikuPorts Node 20 does not meet the runtime minimum, and AIX has no verified native player package route. Non-systemd/BSD/Termux background schedulers remain unavailable until they can demonstrate the existing occurrence/session/retry/catch-up guarantees. SOCKS transport and broader hardware wake verification are future work.

External owner-controlled check: the upstream Vercel preview reports “Authorization required to deploy.” Verification for this fork contribution is recorded in the linked fork CI runs; no deployment authorization, merge, or release has been performed.

Rollback and review

The owner can revert the initiative's commits or restore the previous installed package. There is no schema or lockfile migration to undo. Back up the library before changing versions. If this version registered alarm tasks, remove/repair them through its normal CLI while it remains installed, verify native cleanup, then re-register using the selected version. Preserve failed-cleanup and unverified live ownership records for diagnosis. Rendering/network environment overrides can be removed independently.

• Check each reference tier against exact runtime/guest results, install modes, and artifact hashes.
• Review the rich baseline and intentional ASCII captures, screen-reader output, narrow-terminal navigation, and keyboard/polling assertions.
• Review literal argument/environment propagation across POSIX, systemd, Windows XML, PowerShell, and terminal boundaries.
• Exercise optional desktop failures and scheduler cleanup on a representative real desktop before extending its advertised feature coverage.
• Confirm direct authenticated loopback traffic, proxy diagnostics, permissions, failed-write preservation, and stored-data compatibility.
• Keep the expanded required CI and packed playback gates in the release process, and retain the documented experimental limits.

The PR remains draft for owner review. It has not been merged or published.

[vercel]

@MrSeizy is attempting to deploy a commit to the Viewport Team on Vercel.

A member of the Team first needs to authorize it.

[MrSeizy]

The latest update, ed01e85, addresses all nine findings from the review of 7762f93. It strengthens the cross-platform work already in this PR, covering installation guidance, terminal and scheduler launches, alarm recovery, and desktop helpers.

Finding	What changed and why
1. Alarm deletion failures	Deletion now saves the alarm as disabled before attempting native cleanup. If that first save fails, native cleanup does not start. If cleanup or the final removal fails, the disabled definition remains available for repair. The whole operation is awaited, reports the failed phase, and releases the busy row without an unhandled rejection.
2. Storage identity across launches	Terminal and scheduler launches preserve supported current, legacy, and XDG storage selectors through one environment contract. Conflicting inherited selectors are removed, and relative paths are resolved against the invoking directory, so a changed child working directory cannot silently select another library, cache, or runtime location.
3. Windows task cleanup	Removal verifies the exact named task through structured Task Scheduler COM/HRESULT results instead of relying on English error messages. Only confirmed absence permits cleanup; access denial, malformed responses, and uncertain failures retain repair artifacts.
4. Terminal alias argument handling	QTerminal and x-terminal-emulator forwarding preserve literal executable paths and arguments, including spaces, apostrophes, shell metacharacters, flags, and multiple arguments.
5. Overlapping system-volume ownership	Alarm runners now share one original output snapshot across processes and library profiles. Mutations are serialized, and only the final participant restores the baseline. Failed acquisitions and restorations remain recoverable. Native writes are journaled so crash recovery waits for a surviving mixer helper to exit before another write. Playback handoff preserves the current output and waits for the ownership change; its request deadline accommodates lock contention.
6. Desktop helper lifecycle	Timed-out clipboard helpers and launch bootstraps receive bounded SIGTERM/SIGKILL escalation with exit handling. Successful long-lived browser openers remain detached. Real child-process regressions cover helpers that ignore SIGTERM.
7. Duplicated installation policy	Setup commands and ordinary installation hints now use the same package recipes, including elevation and prerequisites. Platform-specific manual guidance remains explicit, including Scoop extras and BSD/Termux requirements. Linux OS-release reading is consolidated.
8. Obsolete exports and forwarding code	Removed test-only noColorRequested, openExternalCommand, and clipboardCommands exports, the player/command.ts forwarding module, and redundant executable, terminal, IPC, and package wrappers. Production callers and tests use the actual platform entry points; the packed playback harness's dynamic import was migrated too.
9. Duplicate CI work	Removed repeated packed normal/omit-optional installation checks and their duplicate artifact upload from the Linux playback matrix. The main verification matrix retains those packed-install gates, and the distinct playback smoke jobs remain.

Regression coverage exercises combined native/storage deletion failures, clean and conflicting child environments, changed working directories, localized Windows cleanup outcomes, terminal alias quoting, overlapping runners in separate processes, reverse release order, failed persistence and restoration, lock contention during HTTP handoff, dead owners with surviving native helpers, and actual helper termination. Reliability and privacy documentation now explain the shared volume state and crash-repair procedure.

Validation run before committing:

• Node 22.23.2 and Node 24.20.0 on native macOS ARM64: each full suite passed 1,983 tests across 95 files, with 9 platform-specific skips. The separate Node package-harness suite passed 12 tests.
• Fresh packaged installs on both Node versions: normal and --omit=optional modes passed CLI/help/doctor, offline cache, import/export, MCP with 31 tools, and real native mpv IPC readiness, volume, pause, resume, and stop using null audio.
• Checks passed: check, lint, build, check:package, pack:check, smoke:data, smoke:mcp, smoke:playback, docs:check, docs:build, audit:runtime, audit:docs, actionlint, and git diff --check. Runtime and documentation audits reported zero vulnerabilities. An isolated setup dry run also produced the expected installation plan.
• A final manual and independent adversarial review led to additional fixes for relative launch paths, failed volume acquisition, handoff timing, orphan native helpers, and the packed harness import. Those corrections are included in this commit and the final validation above.

The 22/22 CI result in the PR description belongs to 7762f93. No fork Actions run for ed01e85 was listed when this comment was prepared; the upstream Vercel check still reports “Authorization required to deploy.” The new local results do not establish native Windows/Linux/BSD desktop or scheduler behavior, actual OS mixer behavior, or audible hardware playback. An incomplete native-helper journal deliberately blocks automatic volume changes until the documented restart/repair procedure; PID reuse is treated conservatively.