Merge remote-tracking branch 'origin/main' into docs/real-mac-air-test

# Conflicts: # docs/current-support-matrix.md
2026-10-26 15:02:22 +01:00 · 2026-10-26 11:44:18 +11:00 · 2026-10-26 10:35:28 +11:00 · 2026-10-26 10:30:30 +11:00
6 changed files with 147 additions and 11 deletions
@@ -173,16 +173,39 @@ distribution's. If you already have `adb`, the app uses yours.
 <details>
 <summary><b>macOS: the app isn't notarized</b></summary>

-There's no paid Apple developer account behind it, so macOS says the app is
-damaged or can't be checked. Drag it to Applications, then clear the download
-quarantine once, only for a download you trust from the releases linked above:
+The app has an **ad hoc signature**, no Apple Developer ID signature, and no
+notarization. The DMG is unsigned. First verify the download against the
+`SHA256SUMS` from the same release, then open the DMG and drag **Frame Control**
+to **Applications**.
+
+Check your processor before opening: v0.4.36 and earlier publish only
+`mac-arm64` for Apple Silicon. On an Intel Mac, this build cannot run;
+removing quarantine or installing Rosetta does not make an ARM app run on Intel.
+On a real Intel MacBook Air with macOS 15.7.7, opening v0.4.35 and v0.4.36
+reported: **“The application cannot be opened because it has an incorrect
+executable format.”** This is an architecture failure, not an observed
+Gatekeeper warning. See the [real-Mac test record](docs/evidence/mac-desktop-2026-10-26.md).
+
+On a compatible Mac, if macOS blocks an unverified developer, try opening the
+app once, then go to **System Settings → Privacy & Security → Open Anyway**
+and confirm **Open**. Only do this for a download you verified and trust.
+[Apple's opening instructions](https://support.apple.com/102445) describe the
+current security controls. The exact warning and this override flow have not
+yet been verified here on Apple Silicon.
+
+If a trusted, verified copy still reports “damaged” and offers no Open Anyway
+option, the Terminal fallback removes only this app's download quarantine
+(it does not sign or notarize the app):

 ```sh
 xattr -dr com.apple.quarantine "/Applications/Frame Control.app"
 ```

-The first time, macOS also asks to allow local network access (for SSH) and
-control of Terminal (for the password prompts).
+Then open it from Applications. Do not disable Gatekeeper globally. Depending
+on the features you use, macOS may also request Local Network access, permission
+to control Terminal, or Screen Recording; approve only the feature you intend
+to use. Those permission prompts were not verified in the release test above.
+
 </details>

 <details>
@@ -1,12 +1,12 @@
 {
  "name": "frame-control",
-  "version": "0.4.38",
+  "version": "0.4.37",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "frame-control",
-      "version": "0.4.38",
+      "version": "0.4.37",
      "license": "MIT",
      "devDependencies": {
        "electron": "^44.4.5",
@@ -1,7 +1,7 @@
 {
  "name": "frame-control",
  "productName": "Frame Control",
-  "version": "0.4.38",
+  "version": "0.4.37",
  "description": "Desktop app for managing a Valve Steam Frame over SSH",
  "private": true,
  "main": "main.js",
@@ -1,9 +1,10 @@
 # What we have tested

-Current for Frame Control **v0.4.38**, 26 October 2026. “Real Frame + physical PC” means an actual headset and a non-virtual computer. “VM only” means a Windows virtual machine, sometimes connected to the real Frame. A CI test or a simulated device is **not** a physical hardware test. The date/version column is the last relevant check, not a promise that every new release was retested on that platform. See each link for the exact procedure and limits.
+Current for Frame Control **v0.4.37**, 26 October 2026. “Real Frame + physical PC” means an actual headset and a non-virtual computer. “VM only” means a Windows virtual machine, sometimes connected to the real Frame. A CI test or a simulated device is **not** a physical hardware test. The date/version column is the last relevant check, not a promise that every new release was retested on that platform. See each link for the exact procedure and limits.

 | Feature | Real Frame + physical PC tested | VM only | Untested or limited | Last check and proof |
 |---|---|---|---|---|
+| Mac desktop release — tested on a real Mac | Physical MacBook Air (MacBookAir9,1), Intel Core i3, macOS 15.7.7 (24G720): v0.4.35/v0.4.36 DMGs verified and installed; both fail to launch because they are ARM64-only. Separate Intel candidate launched: UI, native preference read/write (restored), bundled Python logs, latest-version check and offline OBS Start/Stop checked; released UI browsed 116 Decky store entries | No | Candidate results are not released-build acceptance. Native Open at Login state, Gatekeeper override, real OBS/Frame stream, native settings across restart, headset transfer and wearer interaction remain unverified | 26 Oct, v0.4.35/v0.4.36 and Intel candidate `6ea9eb2`: [real-Mac evidence](evidence/mac-desktop-2026-10-26.md) |
 | Core title smoke test | Linux lxso2 installed and removed reserved native/Proton titles on the real Frame; all 13 steps passed. ARM64 and Windows titles launched | No | The x86_64 title could not launch because Steam Linux Runtime 4.0 was not installed. The headset was unworn; visible rendering and controller input were not checked. Other feature paths retain their separate limits below | 26 Oct, v0.4.37 tag `5239dae`, Frame OS 0.5.6 build `20261022.6153909`: [release smoke evidence](evidence/v0437-release-smoke-2026-10-26.md); [earlier detailed results](evidence/round2-smoke-2026-10-25.json) |
 | Windows desktop in the headset | No physical Windows PC test | Windows 11 VM sent a whole desktop to a real Frame; this used an intermediate fix, not the final native DLL | Physical GPU, capture and controller input; individual windows unavailable in bundled DXGI build | 24 Oct, v0.4.10 installer + candidate fix: [VM log](evidence/windows-vm-2026-10-24.md), [PC guide](pc-in-headset.md) |
 | Linux desktop in the headset | No | No | Native Linux PC capture is disabled; lxso2 lacked a desktop portal and PipeWire session. The separate Steam `-pipewire` helper is not Frame Control's PC capture | 24 Oct, v0.4.17: [host audit](evidence/linux-pc-host-lxso2-2026-10-24.md), [Steam helper PR #163](https://github.com/saphid/frame-control/pull/163) |
@@ -23,7 +24,7 @@ Current for Frame Control **v0.4.38**, 26 October 2026. “Real Frame + physical
 | Open at login | No Frame needed; Linux autostart file toggled on a physical Linux host with an isolated config directory | No | A full login session and physical Windows/macOS host login have not been checked; OS API calls were unit tested | 25 Oct, v0.4.26: [PR #189](https://github.com/saphid/frame-control/pull/189) |
 | Local Frame Control extensions | Example panel displayed live Frame status in a browser preview; the real Frame served a read-only example in the experimental headset panel | No | No wearer-visible extension view; third-party extensions and physical Windows/macOS extension folders untested | 25 Oct, v0.4.29: [PR #194](https://github.com/saphid/frame-control/pull/194), [PR #201](https://github.com/saphid/frame-control/pull/201), [extension guide](extensions.md) |
 | Experimental Frame Control SteamVR panel | Frame OS 0.5.6 registered and served the opt-in overlay. A later unattended check safely woke SteamVR and found the panel in stereo compositor and mirror captures; it removed its temporary service and restored power settings | No | No person wore the headset for that check. Physical controller input, scrolling, VR keyboard, comfort and legibility remain unverified. The large status view has browser and packaging checks, not a wearer review | 25 Oct, v0.4.29–0.4.37: [panel PR #201](https://github.com/saphid/frame-control/pull/201), [unattended evidence](evidence/framey-vr-2026-10-25/README.md), [worn checklist](framey-vr-check.md) |
-| Experimental Decky Loader manager | Frame OS 0.5.6 ARM64 user-service install/status/update/remove and managed ProtonDB install/update/remove passed earlier. A private Decky 3.3.0 service returned read-only ProtonDB and Steam Status setting RPCs; a later locked check verified the official Notebook default drawing/save/reopen flow and Simple Timer backend events in local Chromium | No | The loader remains opt-in. Installs/updates reject an archive whose Decky name collides with another installed plugin before download and under the headset transaction lock; this safety path has host/fake Frame tests, not a new real-headset collision test. The exact-version official catalog covers 116 plugins: 1 works (Notebook default flow only), 44 partial, 60 broken and 11 not applicable. Most official backends and VR controls remain unverified. Physical controller use and wearer-visible official panels remain unverified | 26 Oct, v0.4.31–0.4.38: [managed store PR #208](https://github.com/saphid/frame-control/pull/208), [name-collision PR #269](https://github.com/saphid/frame-control/pull/269), [catalog PR #266](https://github.com/saphid/frame-control/pull/266), [backend event evidence](evidence/framey-events-backend-2026-10-26.json), [compatibility table](framey-compatibility.md) |
-| Experimental Framey VR plugin panels and store | An unattended Frame OS 0.5.6 run showed the Framey sample panel in stereo compositor and mirror captures. Synthetic OpenVR clicks changed a live sample setting, read its Decky backend file and confirmed it after a fresh iframe reopen | No | This was the repository sample, not an official store plugin. Physical controllers, native scrolling, VR keyboard, wearer comfort and legibility remain unverified. CSS Loader and SteamGridDB exact archives passed fake Frame install/remove and panel packing; this does not establish theme or artwork controls in VR. Panel-local backend events and React toasts have local/real-backend checks, but no wearer review. Pause Games and Tailscale Control settings render in local Chromium; their live actions are unverified. The 116-plugin catalog had 60 fake installs/removals and 56 expected blocks; 98 local Chromium initializers were ready and 18 failed. Notebook is marked works only for its default drawing/save/reopen flow | 26 Oct, v0.4.38: [unattended sample evidence](evidence/framey-vr-2026-10-25/README.md), [backend event PR #270](https://github.com/saphid/frame-control/pull/270), [settings/cache PR #271](https://github.com/saphid/frame-control/pull/271), [worn checklist](framey-vr-check.md) |
+| Experimental Decky Loader manager | Frame OS 0.5.6 ARM64 user-service install/status/update/remove and managed ProtonDB install/update/remove passed earlier. A private Decky 3.3.0 service later returned read-only ProtonDB and Steam Status setting RPCs through Steam CEF; it was removed under the shared lock | No | The loader remains opt-in. The exact-version official catalog covers 116 plugins: 0 works, 43 partial, 62 broken and 11 not applicable. Fake Frame transport and local Chromium do not prove official plugin backends or VR controls. Physical controller use and wearer-visible official plugin panels remain unverified | 25–26 Oct, v0.4.31–0.4.37: [managed store PR #208](https://github.com/saphid/frame-control/pull/208), [catalog PR #266](https://github.com/saphid/frame-control/pull/266), [backend evidence](evidence/framey-official-backend-2026-10-25.json), [compatibility table](framey-compatibility.md) |
+| Experimental Framey VR plugin panels and store | An unattended Frame OS 0.5.6 run showed the Framey sample panel in stereo compositor and mirror captures. Synthetic OpenVR clicks changed a live sample setting, read its Decky backend file and confirmed it after a fresh iframe reopen | No | This was the repository sample, not an official store plugin. Physical controllers, native scrolling, VR keyboard, wearer comfort and legibility are unverified. CSS Loader and SteamGridDB exact archives passed fake Frame install/remove and panel packing; this does not establish theme or artwork controls in VR. React toast content is tested in the host and fake Frame only; it is a panel notice, not a Steam system notification. The 116-plugin catalog had 60 fake installs/removals and 56 expected blocks; 96 local Chromium initializers were ready and 20 failed. No plugin is marked fully working | 25–26 Oct, v0.4.37: [unattended evidence and cleanup](evidence/framey-vr-2026-10-25/README.md), [CSS/SteamGridDB PR #257](https://github.com/saphid/frame-control/pull/257), [legacy bridge PR #261](https://github.com/saphid/frame-control/pull/261), [UI shims PR #263](https://github.com/saphid/frame-control/pull/263), [catalog PR #266](https://github.com/saphid/frame-control/pull/266), [toast PR #267](https://github.com/saphid/frame-control/pull/267), [worn checklist](framey-vr-check.md) |

 Release notes must preserve these limits until a newer recorded check changes them. When a feature is retested, add its date, exact app/Frame version, host type and proof here. The older [v0.3.1 matrix](support-matrix.html) is a historical snapshot and does not describe current coverage.
@@ -0,0 +1,112 @@
+# Physical Mac desktop check, 26 October 2026
+
+Host: **MacBook Air (MacBookAir9,1), Intel Core i3 1.1 GHz, macOS 15.7.7
+(24G720), x86_64**. This is physical hardware. The console is an unattended
+server with display/automation restrictions. No Apple Silicon runtime result
+is inferred from this test.
+
+## Released installers: verified, installed, cannot run on Intel
+
+GitHub's latest release was v0.4.35 at the start; v0.4.36 became latest during
+the check. Each DMG and its SHA256SUMS were downloaded from that exact release
+with `gh release download`. Both passed `shasum -a 256 -c SHA256SUMS
+--ignore-missing` (only the downloaded asset was checked):
+
+| Release | Asset | SHA-256 |
+|---|---|---|
+| v0.4.35 | Frame-Control-mac-arm64.dmg | `eda670748679ca02fcf242870cd53954b22cf8b93af47a193c9903bd08a8334f` |
+| v0.4.36 | Frame-Control-mac-arm64.dmg | `4d13068f0cfd3616823d63c82333afa7e368c1d57d375e9564f5f7ed4f0ebbd7` |
+
+Each read-only DMG was mounted with `hdiutil attach -readonly -nobrowse`.
+There was no existing `/Applications/Frame Control.app`; the app was copied
+there with `ditto`, the command-line equivalent of the DMG's drag to
+Applications. `open "/Applications/Frame Control.app"` returned exactly:
+
+> The application cannot be opened because it has an incorrect executable format.
+
+`file` identified the executable as `Mach-O 64-bit executable arm64`.
+`codesign -dv` identified an ad hoc signature with no TeamIdentifier. The
+v0.4.35 `spctl -a -vv` assessment returned `rejected`. The v0.4.36 assessment
+stalled and is not counted as a completed assessment.
+
+**No Gatekeeper warning dialog was observed.** LaunchServices rejected the
+architecture first. The CLI download had no `com.apple.quarantine` attribute,
+so this was not a browser-quarantine test. Neither right-click Open, Open
+Anyway nor removing quarantine was tested. On this Intel Mac there is no
+honest opening workaround for either released ARM64 app. Rosetta does not
+run ARM64 apps on Intel. The README now separates that fact from Apple's
+recommended Open Anyway flow for compatible Macs and labels the latter
+unverified here. No global Gatekeeper setting was changed.
+
+## Separate Intel candidate: partial native runtime pass
+
+[PR #262](https://github.com/saphid/frame-control/pull/262), commit `6ea9eb2`,
+adds native x64 DMG/ZIP builds, pinned x64 Python, an x86_64 Swift helper, and
+CI architecture checks. Swift 6.2.4 rejected an ambiguous
+`Data.withUnsafeMutableBytes` overload in the helper; an explicit
+`UnsafeMutableRawBufferPointer` annotation compiled successfully on this Air.
+
+`npm run dist:mac:x64` completed locally, producing an ad hoc signed app,
+ZIP and DMG. The unpacked candidate was copied to
+`/Applications/Frame Control Intel Test.app` and launched with telemetry off,
+a task-local server data directory and a temporary loopback debug port.
+This is **not** the published v0.4.36 binary.
+
+The first launch stalled for several minutes before app code ran. A process
+sample showed only `_dyld_start`, a 12 KiB footprint and no loaded image
+list, while `syspolicyd` used about 89% CPU. It later proceeded without any
+system-service restart; the app window and server loaded. The initial stall
+is a host observation, not proof of a Frame Control bug. Restarting that
+security daemon was rejected by automatic approval review, and was not done.
+
+| Check | Observed result and limit |
+|---|---|
+| Native window and IPC bridge | The Electron renderer displayed Apps and the offline identity warning; `window.frameApp` was present. Native renderer inspected through its temporary loopback CDP port; this does not prove every macOS permission dialog or physical click |
+| Settings | Native preference read returned `{}`. Writing `mvSeparate="0"` read back correctly. The original preference file was restored byte-for-byte (or removed when originally absent) in a finally block. Persistence across an app restart is not claimed |
+| Open at Login | Source is opt-in and focused login-item tests passed. Native menu read via System Events timed out; an OS login session and actual checkbox state remain unverified. No login item was enabled |
+| Logs | `~/Library/Logs/Frame Control/server.log` exists. Its startup line proves the candidate used `Contents/Resources/python/bin/python3` and its bundled `ui/server.py`; HTTP reads and offline failures were logged. Show Server Log menu interaction was not verified |
+| Update check | Actual `frameApp.update.check()` completed with `status="none"`, `current="0.4.36"`, latest `0.4.36`, and `error=null`. No update was installed; native dialog dismissal was not verified |
+| OBS setup and lifecycle | Native status reported supported/idle, Start on port 15123 reported starting, Stop reported stopping, then idle. The Frame's SSH identity rejection prevented a headset stream. This checks local lifecycle only: no OBS app, audio/video delivery or receiver tested |
+| Decky store | The exact released UI/server resources, separately served by this Mac's existing Python 3.9.6, loaded 116 official entries in local Chromium. Forty rows rendered; searching ProtonDB found ProtonDB Badges 1.3.4; all Install buttons stayed disabled while offline. No loader or plugin was installed. [Browser screenshot](mac-decky-browser-2026-10-26.png) |
+| Other UI | Released Apps, Settings, Privacy & updates, Tools, Capture & Live and Decky views rendered. The privacy page correctly reported telemetry blocked by `FRAME_CONTROL_TELEMETRY=0`; sharing/contact choices were left alone. The activity log displayed the offline failure. The browser path hides native OBS buttons as designed; it is not a substitute for the native lifecycle check above |
+| Framey preview | No standalone local preview control was found in the desktop UI. The Framey panel belongs to the headset runtime; no VR or plugin-backend result is claimed |
+
+The released server refused a stale SSH host identity rather than silently
+trusting it. That safety check was preserved; no host pin was replaced just
+to make the test pass. Capture, media, game launches, power controls, installs,
+sign-ins and notifications were not triggered without a working connection.
+
+## Headset: read-only relay checks, no changes
+
+`frame.local` resolved on the Air, but direct TCP/SSH did not connect. The
+coordinator host lxso2 could reach it. The app's read-only `frame_status.py`
+was piped through lxso2 to the Frame and returned:
+
+- SteamOS **0.5.6**, build **20261022.6153909**, variant `vr`.
+- Battery **99%, Charging**.
+- Home storage: 996,984,774,656 bytes total, 769,023,275,008 bytes free.
+- A read-only search counted **14** Steam screenshot JPEGs; none was copied.
+
+The shared `/tmp/frame-test.lock` was owned by another Framey test on each
+check. This job did not acquire, remove or replace it. File upload/delete,
+OBS on the device and every other headset mutation were skipped. These relay
+reads do not prove the native Mac app's direct SSH or file-transfer path.
+The headset was never wiped or rebooted.
+
+## Validation and follow-up
+
+A disposable Linux checkout of exact commit `6ea9eb2` on lxso2 passed:
+**1,590 server tests (16 skipped)** and **46 app tests**. On the physical Air,
+**14 focused login-item/preferences/OBS tests** and **18 website tests** passed.
+Full Mac server/release suites were attempted but spawned helper programs
+stalled and timed out during the policy-service problem; they are not a pass.
+Node 22's complete app run cancelled sign-in tests around an unreferenced
+timeout; the exact same app suite passed on lxso2. CI uses Node 24.
+
+Required next steps: pass exact-head Mac packaging/architecture CI, publish
+an Intel asset through coordinator job mppkd9qczt, then repeat a normal
+browser-download/quarantine installation of that release on this Air. Verify
+Open Anyway and Open at Login through an authorized interactive console.
+Acquire the shared headset lock before a temporary transfer or real OBS test.
+Preserve all unverified labels until those checks actually pass. PR #113 was
+not changed. No social post was made.
Author	SHA1	Message	Date
Alex Southwell	0a463dea23	Merge remote-tracking branch 'origin/main' into docs/real-mac-air-test # Conflicts: # docs/current-support-matrix.md	2026-10-26 11:44:18 +11:00
Alex Southwell	19e8b826c6	Merge remote-tracking branch 'origin/main' into docs/real-mac-air-test	2026-10-26 10:35:28 +11:00
Alex Southwell	879e84468b	Record physical Intel Mac testing and clarify unsigned app opening	2026-10-26 10:30:30 +11:00