docs: update TODO_AGENTS — current display_control status + future ideas section

docs/build: update README + compiled dist for list-modes/set-mode features
README: - set_display_layout: note idempotent behavior (no flicker if already in state) - add list_display_modes and set_display_mode rows to bridge table - add list-modes and set-mode to Option B test commands dist/: compiled output from tsc (system_handlers, preload, index)
2026-05-20 18:43:14 -04:00 · 2026-05-20 18:27:58 -04:00 · 2026-05-20 18:24:33 -04:00 · 2026-05-20 18:17:17 -04:00 · 2026-05-20 18:16:43 -04:00 · 2026-05-20 18:14:26 -04:00
20 changed files with 1483 additions and 195 deletions
--- a/README.md
+++ b/README.md
@@ -284,7 +284,7 @@ to change.

 | Method | Description |
 | --- | --- |
-| `launch_presentation({path, app?, os?})` | Platform-aware launcher. Resolves `[home]`/`[tmp]` placeholders. **Note:** uses legacy `-e` flag for AppleScript; prefer `copy_from_cache_to_temp` + `run_osascript` for new flows. |
+| `launch_presentation({path, app?, os?})` | Platform-aware launcher. Resolves `[home]`/`[tmp]` placeholders. Hardened (2026-05-11): AppleScript written to temp `.scpt` file, same as `run_osascript`. For new flows prefer `copy_from_cache_to_temp` + `run_osascript` for full control. |
 | `control_presentation({app, action})` | Slide navigation (`next`/`prev`/`start`/`stop`) for PowerPoint or Keynote via AppleScript. macOS only. |

 ### System Management (Phase 5)
@@ -294,9 +294,11 @@ to change.
 | `get_device_config()` | Returns hydrated device config injected at startup from `seed.json` + API. |
 | `get_device_info()` | Returns OS metadata: platform, hostname, IPs, CPU count, free RAM, home/tmp paths. |
 | `window_control({action, value?})` | Electron window: maximize, minimize, restore, close, fullscreen, kiosk, devtools, reload. |
-| `set_wallpaper({path})` | Sets desktop wallpaper. macOS (AppleScript) + Linux (gsettings/Gnome). |
+| `set_wallpaper({path?, url?, url_external?, display?, api_key?, account_id?})` | Sets desktop wallpaper. Accepts a local `path` or downloads from `url` (cached to `~/Library/Caches/OSIT/wallpaper/`). `url_external` sets a separate image on the projector/second display. `display`: `'all'` (default) \| `'primary'` \| `'external'`. macOS only in production; Linux returns a dev-mode preview payload without applying. |
 | `power_control({action})` | Shutdown, reboot, or sleep. macOS + Linux. Requires sudo for shutdown/reboot. |
-| `set_display_layout({mode, configStr?})` | Mirror/extend displays via bundled `displayplacer` binary. macOS only. `configStr` is the output of `displayplacer list` for that machine, stored in `event_device.data_json.displayplacer_config_mirror` / `displayplacer_config_extend`. Required — silently no-ops without it. |
+| `set_display_layout({mode, configStr?})` | Mirror/extend displays. macOS only. **Idempotent** — returns success immediately if the displays are already in the requested state (no flicker). **Primary path:** bundled `display_control` binary (native CoreGraphics, no Homebrew). **Fallback:** `displayplacer` — used when the binary is absent or when a `configStr` override is set. `configStr` is a full `displayplacer` string stored in `event_device.data_json` for per-device tuning. Build `display_control` via `scripts/build-display-control.sh` on a Mac and commit `resources/bin/display_control`. |
+| `list_display_modes()` | Returns all online displays with every usable `CGDisplayMode` per display: logical size, pixel size, refresh rate, HiDPI flag, and which mode is currently active. macOS only. JSON is parsed for you — result is `{ success, displays: DisplayInfo[] }`. Use this to populate a resolution picker in the UI. |
+| `set_display_mode({display_index, width, height, refresh_rate?, hidpi?})` | Sets the resolution/refresh of one display via `CGConfigureDisplayWithDisplayMode`. `display_index` matches the `index` from `list_display_modes`. `hidpi`: `true` = force HiDPI (Retina scaling), `false` = force non-HiDPI, `null`/omit = auto (prefers HiDPI on built-in, non-HiDPI on externals). Picks the highest available refresh rate when multiple modes match. macOS only. |
 | `manage_recording({action, options?})` | Screen recording via bundled `aperture` binary. macOS only. |
 | `update_app(args)` | **Stub.** Downloads update package but does not install. Not functional. |
 | `list_tools()` | Returns a self-describing manifest of all available bridge functions. |
@@ -352,6 +354,60 @@ See `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` Section 8
 - **Handlers:** OS-level logic in `src/main/shell_handlers.ts`, `src/main/file_handlers.ts`, and `src/main/system_handlers.ts`.
 - **Types:** Shared TypeScript interfaces in `src/shared/types.ts`.

+### One-Time: Build the `display_control` Binary (macOS)
+
+The `display_control` binary provides native CoreGraphics display mirror/extend without any Homebrew dependency. It must be compiled on a Mac (Xcode CLT required) and committed to the repo so it is bundled into every packaged app. Produces a universal binary (x86_64 + arm64) that runs on both Intel and Apple Silicon Macs.
+
+Rebuild only if `scripts/display_control.m` changes.
+
+#### Option A — From the Linux workstation (preferred)
+
+Laptop 01 (`192.168.32.101`) is the designated build Mac — Xcode CLT is installed there.
+The remote build script copies the source over SSH, compiles on that Mac, and pulls the binary back.
+
+```bash
+# From the repo root on the workstation:
+./scripts/remote-build-display-control.sh
+
+# Override the build Mac IP if needed:
+./scripts/remote-build-display-control.sh 192.168.32.102
+```
+
+The script prints `file resources/bin/display_control` at the end. Confirm both arches appear:
+```
+resources/bin/display_control: Mach-O universal binary with 2 architectures: [x86_64] [arm64]
+```
+
+Then commit:
+```bash
+git add resources/bin/display_control
+git commit -m "build: update display_control binary (universal)"
+```
+
+#### Option B — Directly on a Mac
+
+If you have repo access on the Mac itself (Xcode CLT required — `xcode-select --install`):
+
+```bash
+./scripts/build-display-control.sh
+# Expected last output line: x86_64 arm64
+
+# Test with a second display connected:
+./resources/bin/display_control status
+./resources/bin/display_control extend
+./resources/bin/display_control mirror
+./resources/bin/display_control list-modes
+./resources/bin/display_control set-mode 0 1920 1080
+./resources/bin/display_control set-mode 1 1920 1080 --refresh 60 --no-hidpi
+
+git add resources/bin/display_control
+git commit -m "build: update display_control binary (universal)"
+```
+
+Once committed, `brew install displayplacer` is no longer required on any venue Mac. The `displayplacer` fallback remains in the handler only for `configStr` per-device overrides.
+
+---
+
 ### Build Requirements (System Dependencies)

 `bsdtar` (libarchive) must be present on the build host. It is used by the `postinstall` patch
--- a/dist/main/index.js
+++ b/dist/main/index.js
@@ -50,8 +50,8 @@ async function createWindow() {
        cachedFullConfig = await (0, api_client_1.fetchFullConfig)(cachedSeed);
    }
    mainWindow = new electron_1.BrowserWindow({
-        width: 1600,
-        height: 900,
+        width: 1280,
+        height: 800,
        title: 'OSIT Aether Launcher (Native)',
        webPreferences: {
            preload: path.join(__dirname, '../preload/index.js'),
@@ -59,6 +59,9 @@ async function createWindow() {
            nodeIntegration: false,
        },
    });
+    // Let the native window manager maximize — more reliable than using screen.workArea,
+    // which Electron under-reports on KDE and other Linux DEs.
+    mainWindow.maximize();
    let targetUrl = 'http://demo.localhost:5173';
    if (cachedFullConfig && cachedFullConfig.native_device) {
        const device = cachedFullConfig.native_device;
@@ -82,15 +85,29 @@ async function createWindow() {
 (0, shell_handlers_1.registerShellHandlers)();
 (0, file_handlers_1.registerFileHandlers)();
 (0, system_handlers_1.registerSystemHandlers)();
-electron_1.app.on('ready', createWindow);
-electron_1.app.on('window-all-closed', () => {
-    if (process.platform !== 'darwin')
-        electron_1.app.quit();
-});
-electron_1.app.on('activate', () => {
-    if (mainWindow === null)
-        createWindow();
-});
+// Single instance lock — if another instance is already running, focus it and quit.
+const gotTheLock = electron_1.app.requestSingleInstanceLock();
+if (!gotTheLock) {
+    electron_1.app.quit();
+}
+else {
+    electron_1.app.on('second-instance', () => {
+        if (mainWindow) {
+            if (mainWindow.isMinimized())
+                mainWindow.restore();
+            mainWindow.focus();
+        }
+    });
+    electron_1.app.on('ready', createWindow);
+    electron_1.app.on('window-all-closed', () => {
+        if (process.platform !== 'darwin')
+            electron_1.app.quit();
+    });
+    electron_1.app.on('activate', () => {
+        if (mainWindow === null)
+            createWindow();
+    });
+}
 electron_1.ipcMain.handle('get-seed-config', async () => cachedSeed || await (0, config_loader_1.loadSeedConfig)());
 electron_1.ipcMain.handle('get-device-config', async () => cachedFullConfig);
 electron_1.ipcMain.handle('get-jwt', async () => null);
--- a/dist/main/index.js.map
+++ b/dist/main/index.js.map
@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/main/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/main/index.ts"],"names":[],"mappings":"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"}
--- a/dist/main/shell_handlers.js
+++ b/dist/main/shell_handlers.js
@@ -224,65 +224,115 @@ end tell
    });
    electron_1.ipcMain.handle('native:list-tools', async () => {
        return [
+            // --- Config & Info ---
+            {
+                name: 'get_device_config',
+                description: 'Returns hydrated device config injected at startup from seed.json + API.',
+                params: {}
+            },
+            {
+                name: 'get_device_info',
+                description: 'Returns OS metadata: platform, hostname, IPs, CPU count, free RAM, home/tmp paths.',
+                params: {}
+            },
+            // --- File Cache ---
+            {
+                name: 'check_cache',
+                description: 'Checks if a file exists in the hashed cache. verify_hash:true re-hashes to confirm integrity.',
+                params: { cache_root: 'string', hash: 'string', hash_prefix_length: 'number (optional, default 2)', verify_hash: 'boolean (optional)' }
+            },
+            {
+                name: 'download_to_cache',
+                description: 'Streams a file from the API into the hashed cache with SHA-256 integrity check. Cleans stale .tmp files older than 5 min.',
+                params: { url: 'string', cache_root: 'string', hash: 'string', api_key: 'string', account_id: 'string', hash_prefix_length: 'number (optional, default 2)' }
+            },
+            {
+                name: 'copy_from_cache_to_temp',
+                description: 'Preferred primitive. Copies a cached file to temp with its original filename. Returns { success, path }. Caller decides what to do next.',
+                params: { cache_root: 'string', hash: 'string', temp_root: 'string', filename: 'string', hash_prefix_length: 'number (optional, default 2)' }
+            },
+            {
+                name: 'launch_from_cache',
+                description: 'Combines copy_from_cache_to_temp + execute. Runs native_template after copying — AppleScript string with {{path}} placeholder, or "shell:<cmd>" prefix. Returns error if native_template is null.',
+                params: { cache_root: 'string', hash: 'string', temp_root: 'string', filename: 'string', hash_prefix_length: 'number (optional)', native_template: 'string | null' }
+            },
+            // --- Shell & OS ---
            {
                name: 'open_folder',
-                description: 'Opens a directory in the OS file explorer (Finder/Files/Explorer).',
+                description: 'Opens a directory in the OS file explorer (Finder on macOS).',
                params: { path: 'string' }
            },
            {
                name: 'run_cmd',
-                description: 'Executes an asynchronous shell command with a timeout.',
-                params: { cmd: 'string', timeout: 'number (optional)' }
+                description: 'Async shell command execution with timeout.',
+                params: { cmd: 'string', timeout: 'number (optional, default 30000ms)' }
            },
            {
                name: 'run_cmd_sync',
-                description: 'Executes a synchronous shell command.',
+                description: 'Synchronous shell command execution.',
                params: { cmd: 'string' }
            },
            {
                name: 'run_osascript',
-                description: 'Executes a raw AppleScript string (macOS only).',
+                description: 'Hardened AppleScript executor — writes to temp .scpt file, handles multi-line scripts and paths with special characters. macOS only.',
                params: { script: 'string' }
            },
            {
                name: 'kill_processes',
-                description: 'Forcefully terminates processes by name.',
+                description: 'Terminates processes by name. macOS/Linux: pkill -f. Windows: taskkill /F.',
                params: { process_name_li: 'string[]' }
            },
            {
                name: 'open_local_file_v2',
-                description: 'Opens a local file using the default OS handler.',
-                params: { filePath: 'string' }
+                description: 'Opens a file with its default OS application via shell.openPath.',
+                params: { path: 'string' }
            },
+            {
+                name: 'open_external',
+                description: 'Opens a URL in Chrome, Firefox, or the system default browser.',
+                params: { url: 'string', app: 'chrome | firefox | default (optional)' }
+            },
+            // --- Presentations ---
            {
                name: 'launch_presentation',
-                description: 'Phase 5: Specialized launcher for PowerPoint, Keynote, and LibreOffice with auto-focus.',
-                params: { path: 'string', app: 'default|powerpoint|keynote' }
+                description: 'Platform-aware launcher for PowerPoint, Keynote, LibreOffice. Resolves [home]/[tmp] placeholders. Hardened AppleScript (2026-05-11). Prefer copy_from_cache_to_temp + run_osascript for new flows.',
+                params: { path: 'string', app: 'default | powerpoint | keynote (optional)', os_platform: 'string (optional)' }
            },
            {
                name: 'control_presentation',
-                description: 'Phase 5: Remote navigation for active slideshows.',
-                params: { app: 'powerpoint|keynote', action: 'next|prev|start|stop' }
+                description: 'Slide navigation for active PowerPoint or Keynote via AppleScript. macOS only.',
+                params: { app: 'powerpoint | keynote', action: 'next | prev | start | stop' }
+            },
+            // --- System Management ---
+            {
+                name: 'set_wallpaper',
+                description: 'Sets desktop wallpaper. Downloads from url (cached to ~/Library/Caches/OSIT/wallpaper/) or applies local path. url_external targets projector/second display separately. macOS only in production.',
+                params: { path: 'string (optional)', url: 'string (optional)', url_external: 'string (optional)', display: 'all | primary | external (optional, default all)', api_key: 'string (optional)', account_id: 'string (optional)' }
            },
            {
-                name: 'check_cache',
-                description: 'Checks if a file exists in the local organized cache.',
-                params: { cache_root: 'string', hash: 'string', hash_prefix_length: 'number' }
+                name: 'set_display_layout',
+                description: 'Mirror or extend displays via bundled displayplacer. macOS only. Auto-detects displays when no configStr given; configStr is an optional manual override.',
+                params: { mode: 'mirror | extend', configStr: 'string (optional)' }
            },
            {
-                name: 'download_to_cache',
-                description: 'Downloads a file from the API directly into the native cache.',
-                params: { url: 'string', cache_root: 'string', hash: 'string', api_key: 'string', account_id: 'string' }
+                name: 'window_control',
+                description: 'Electron window management.',
+                params: { action: 'maximize | unmaximize | minimize | restore | close | fullscreen | kiosk | devtools | reload', value: 'boolean (optional, used by fullscreen/kiosk/devtools)' }
            },
            {
-                name: 'launch_from_cache',
-                description: 'Atomic operation: Copies file from cache to temp with original name and launches via specialized handler.',
-                params: { cache_root: 'string', hash: 'string', temp_root: 'string', filename: 'string' }
+                name: 'power_control',
+                description: 'Shutdown, reboot, or sleep the host machine. macOS + Linux. May require sudo for shutdown/reboot.',
+                params: { action: 'shutdown | reboot | sleep' }
            },
            {
-                name: 'get_device_info',
-                description: 'Returns hardware and OS metadata (CPUs, RAM, IP addresses, Hostname).',
-                params: {}
+                name: 'manage_recording',
+                description: 'Screen recording via bundled aperture binary. macOS only.',
+                params: { action: 'start | stop | status', options: '{ fps?, audioDeviceId?, output? } (optional)' }
+            },
+            {
+                name: 'update_app',
+                description: 'STUB: Downloads update package but does not install. Not functional.',
+                params: { source: 'url | file', url: 'string (optional)', path: 'string (optional)' }
            }
        ];
    });
--- a/dist/main/shell_handlers.js.map
+++ b/dist/main/shell_handlers.js.map
--- a/dist/main/system_handlers.js
+++ b/dist/main/system_handlers.js
@@ -100,17 +100,162 @@ function registerSystemHandlers() {
        return { success: true };
    });
    // 2. Set Wallpaper
-    electron_1.ipcMain.handle('native:set-wallpaper', async (event, { path: imagePath }) => {
-        const cleanPath = (0, file_utils_1.expandPath)(imagePath);
-        if (!fs.existsSync(cleanPath))
-            return { success: false, error: 'Image file not found' };
-        if (os.platform() === 'darwin') {
-            const script = `tell application "System Events" to set picture of every desktop to "${cleanPath}"`;
-            return await runExec(`osascript -e '${script}'`);
+    // Supports local path OR URL download. URL images are saved to a stable cache dir
+    // so macOS can reference them persistently after reboot.
+    // display: 'all' (default) | 'primary' (built-in) | 'external' (projector/second screen)
+    // url_external: optional second URL for the external display only.
+    electron_1.ipcMain.handle('native:set-wallpaper', async (event, { path: imagePath, url, url_external, display = 'all', api_key, account_id }) => {
+        // Cache dir: ~/Library/Caches/OSIT/wallpaper on macOS, ~/.cache/osit/wallpaper on Linux.
+        // Using a stable path means macOS keeps the reference across reboots.
+        const wallpaper_cache_dir = os.platform() === 'darwin'
+            ? path.join(os.homedir(), 'Library', 'Caches', 'OSIT', 'wallpaper')
+            : path.join(os.homedir(), '.cache', 'osit', 'wallpaper');
+        async function download_wallpaper_image(image_url, basename) {
+            if (!fs.existsSync(wallpaper_cache_dir)) {
+                fs.mkdirSync(wallpaper_cache_dir, { recursive: true });
+            }
+            // Infer extension from URL path, fall back to .jpg
+            let ext = '.jpg';
+            try {
+                const url_path = new URL(image_url).pathname;
+                const inferred = path.extname(url_path).toLowerCase();
+                if (['.jpg', '.jpeg', '.png', '.webp'].includes(inferred)) {
+                    ext = inferred === '.jpeg' ? '.jpg' : inferred;
+                }
+            }
+            catch { }
+            const dest_path = path.join(wallpaper_cache_dir, basename + ext);
+            const headers = {};
+            if (api_key)
+                headers['x-aether-api-key'] = api_key;
+            if (account_id)
+                headers['x-account-id'] = account_id;
+            try {
+                const response = await (0, axios_1.default)({ method: 'get', url: image_url, responseType: 'stream', headers });
+                const content_type = (response.headers['content-type'] ?? '');
+                if (!content_type.startsWith('image/')) {
+                    response.data.destroy();
+                    return { success: false, error: `URL did not return an image (Content-Type: ${content_type})` };
+                }
+                const writer = fs.createWriteStream(dest_path);
+                response.data.pipe(writer);
+                await new Promise((resolve, reject) => {
+                    writer.on('finish', resolve);
+                    writer.on('error', reject);
+                });
+                const file_size = fs.statSync(dest_path).size;
+                if (file_size === 0) {
+                    try {
+                        fs.unlinkSync(dest_path);
+                    }
+                    catch { }
+                    return { success: false, error: 'Wallpaper download incomplete (0 bytes)' };
+                }
+                return { success: true, path: dest_path };
+            }
+            catch (e) {
+                return { success: false, error: `Wallpaper download failed: ${e.message}` };
+            }
        }
-        else if (os.platform() === 'linux') {
-            // Gnome/Ubuntu default
-            return await runExec(`gsettings set org.gnome.desktop.background picture-uri "file://${cleanPath}"`);
+        // HARDENED: write AppleScript to a temp file, same pattern as native:run-osascript.
+        // The old osascript -e approach breaks on paths with spaces or special characters.
+        async function apply_mac_wallpaper(img_path, display_target) {
+            const escaped = img_path.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+            let script;
+            if (display_target === 'primary') {
+                script = `tell application "System Events"\n\ttell desktop 1\n\t\tset picture to "${escaped}"\n\tend tell\nend tell`;
+            }
+            else if (display_target === 'external') {
+                script = `tell application "System Events"\n\ttell desktop 2\n\t\tset picture to "${escaped}"\n\tend tell\nend tell`;
+            }
+            else {
+                script = `tell application "System Events"\n\ttell every desktop\n\t\tset picture to "${escaped}"\n\tend tell\nend tell`;
+            }
+            const script_path = path.join(os.tmpdir(), `ae_wallpaper_${Date.now()}.scpt`);
+            fs.writeFileSync(script_path, script, 'utf-8');
+            try {
+                return await runExec(`osascript "${script_path}"`);
+            }
+            finally {
+                try {
+                    fs.unlinkSync(script_path);
+                }
+                catch { }
+            }
+        }
+        if (os.platform() === 'darwin') {
+            // Resolve primary image path
+            let primary_path = null;
+            if (imagePath) {
+                const clean = (0, file_utils_1.expandPath)(imagePath);
+                if (!fs.existsSync(clean))
+                    return { success: false, error: 'Image file not found' };
+                primary_path = clean;
+            }
+            else if (url) {
+                const result = await download_wallpaper_image(url, 'wallpaper_primary');
+                if (!result.success || !result.path)
+                    return { success: false, error: result.error };
+                primary_path = result.path;
+            }
+            if (!primary_path && url_external && display === 'external') {
+                const ext_result = await download_wallpaper_image(url_external, 'wallpaper_external');
+                if (!ext_result.success || !ext_result.path)
+                    return { success: false, error: ext_result.error };
+                return await apply_mac_wallpaper(ext_result.path, 'external');
+            }
+            if (!primary_path)
+                return { success: false, error: 'No image source provided' };
+            if (url_external) {
+                // Different images for each display: set primary display first, then external
+                const primary_result = await apply_mac_wallpaper(primary_path, 'primary');
+                if (!primary_result.success)
+                    return primary_result;
+                const ext_result = await download_wallpaper_image(url_external, 'wallpaper_external');
+                if (!ext_result.success || !ext_result.path)
+                    return { success: false, error: ext_result.error };
+                return await apply_mac_wallpaper(ext_result.path, 'external');
+            }
+            else {
+                return await apply_mac_wallpaper(primary_path, display);
+            }
+        }
+        if (os.platform() === 'linux') {
+            // Dev test mode: never touch the desktop on Linux. Running gsettings during
+            // development would reset the dev workstation monitors on every test cycle.
+            // Return what would have run so the Svelte side can show a debug popup.
+            const would_run = [];
+            const cache_dir = wallpaper_cache_dir;
+            if (!imagePath && !url && !url_external) {
+                return { success: false, error: 'No image source provided' };
+            }
+            if (imagePath) {
+                const clean = (0, file_utils_1.expandPath)(imagePath);
+                if (!fs.existsSync(clean))
+                    return { success: false, error: 'Image file not found' };
+            }
+            if (url)
+                would_run.push(`download: ${url}\n  → ${path.join(cache_dir, 'wallpaper_primary.jpg')}`);
+            if (url_external)
+                would_run.push(`download: ${url_external}\n  → ${path.join(cache_dir, 'wallpaper_external.jpg')}`);
+            if (imagePath) {
+                would_run.push(`gsettings set org.gnome.desktop.background picture-uri "file://${(0, file_utils_1.expandPath)(imagePath)}"`);
+            }
+            else if (url) {
+                would_run.push(`gsettings set org.gnome.desktop.background picture-uri "file://${path.join(cache_dir, 'wallpaper_primary.jpg')}"`);
+            }
+            if (url_external) {
+                would_run.push(`(external display: gsettings has no per-display wallpaper support)`);
+            }
+            return {
+                success: true,
+                linux_test_mode: true,
+                platform: 'linux',
+                display,
+                url: url ?? null,
+                url_external: url_external ?? null,
+                would_run
+            };
        }
        return { success: false, error: 'Platform not supported' };
    });
@@ -139,7 +284,7 @@ function registerSystemHandlers() {
        }
        if (!cmd)
            return { success: false, error: 'Action not supported' };
-        // NOTE: These commands often require root. 
+        // NOTE: These commands often require root.
        // For a kiosk, you might configure sudoers to allow this specific command without password.
        return await runExec(cmd);
    });
@@ -215,33 +360,128 @@ function registerSystemHandlers() {
        }
        return { success: false, error: 'Unknown action' };
    });
-    // 6. Set Display Layout (Displayplacer)
+    // 6. Set Display Layout
+    // Primary path: display_control (native CoreGraphics, no external deps).
+    //   Build from scripts/display_control.m via scripts/build-display-control.sh on a Mac.
+    //   Commit the resulting resources/bin/display_control binary to the repo.
+    // Fallback: displayplacer (requires: brew install displayplacer on each venue Mac).
+    //   Also supports per-device configStr override (displayplacer format).
    electron_1.ipcMain.handle('native:set-display-layout', async (event, { mode, configStr }) => {
        if (os.platform() !== 'darwin')
            return { success: false, error: 'Display control only supported on macOS' };
-        const binPath = electron_1.app.isPackaged
-            ? path.join(process.resourcesPath, 'bin', 'displayplacer')
-            : path.join(__dirname, '../../resources/bin/displayplacer');
-        let cmd = '';
+        // Primary: display_control — native CoreGraphics, no Homebrew dependency.
+        // Derived from OSIT MasterKey app (LegacyUtilities.m). No configStr support needed —
+        // CoreGraphics auto-detects all connected displays.
+        const dc_bin = electron_1.app.isPackaged
+            ? path.join(process.resourcesPath, 'bin', 'display_control')
+            : path.join(__dirname, '../../resources/bin/display_control');
+        if (fs.existsSync(dc_bin) && !configStr) {
+            if (mode !== 'mirror' && mode !== 'extend') {
+                return { success: false, error: `Unsupported display mode: ${mode}` };
+            }
+            return await runExec(`"${dc_bin}" ${mode}`);
+        }
+        // Fallback: displayplacer — required when display_control binary is not built yet,
+        // or when a per-device configStr override is set (displayplacer-format string from event_device.data_json).
+        // Install: brew install displayplacer
+        const _dp_candidates = electron_1.app.isPackaged
+            ? [path.join(process.resourcesPath, 'bin', 'displayplacer')]
+            : [
+                path.join(__dirname, '../../resources/bin/displayplacer'),
+                '/opt/homebrew/bin/displayplacer', // Apple Silicon Homebrew
+                '/usr/local/bin/displayplacer', // Intel Homebrew
+            ];
+        const dpPath = _dp_candidates.find(p => fs.existsSync(p)) ?? _dp_candidates[0];
+        // Explicit configStr takes priority — allows manual per-device override.
+        if (configStr) {
+            return await runExec(`"${dpPath}" ${configStr}`);
+        }
+        // Auto-detect via `displayplacer list`.
+        const list_result = await runExec(`"${dpPath}" list`);
+        if (!list_result.success || !list_result.stdout) {
+            return { success: false, error: `displayplacer not available. Build display_control from scripts/build-display-control.sh or run: brew install displayplacer` };
+        }
+        // The command line looks like: displayplacer "id:xxx res:... origin:(0,0) ..." "id:yyy ..."
+        const cmd_line = list_result.stdout.split('\n').find(l => l.trim().startsWith('displayplacer "'));
+        if (!cmd_line) {
+            return { success: false, error: 'Only one display connected or displayplacer list output unrecognised' };
+        }
+        const display_strings = [...cmd_line.matchAll(/"([^"]+)"/g)].map(m => m[1]);
+        if (display_strings.length < 2) {
+            return { success: false, error: 'Only one display found; cannot change layout' };
+        }
        if (mode === 'mirror') {
-            // This usually requires querying current IDs, which is complex.
-            // If configStr is provided (output of 'displayplacer list'), use it.
-            if (configStr) {
-                cmd = `"${binPath}" ${configStr}`;
+            const primary_id_match = display_strings[0].match(/\bid:([^\s]+)/);
+            if (!primary_id_match) {
+                return { success: false, error: 'Could not parse primary display ID from displayplacer output' };
            }
-            else {
-                return { success: false, error: 'Config string required for now' };
+            const primary_id = primary_id_match[1];
+            const mirror_args = display_strings.map((s, i) => {
+                if (i === 0)
+                    return `"${s}"`;
+                const without_existing_mirror = s.replace(/\s*mirror_of_display:\S+/g, '').trim();
+                return `"${without_existing_mirror} mirror_of_display:${primary_id}"`;
+            }).join(' ');
+            return await runExec(`"${dpPath}" ${mirror_args}`);
+        }
+        if (mode === 'extend') {
+            const any_mirrored = display_strings.some(s => /\bmirror_of_display:\S+/.test(s));
+            if (!any_mirrored) {
+                return await runExec(`"${dpPath}" ${display_strings.map(s => `"${s}"`).join(' ')}`);
            }
+            let x_offset = 0;
+            const extend_args = display_strings.map((s) => {
+                const without_mirror = s.replace(/\s*mirror_of_display:\S+/g, '').trim();
+                const res_match = without_mirror.match(/\bres:(\d+)x\d+/);
+                const width = res_match ? parseInt(res_match[1]) : 1920;
+                const updated = without_mirror.replace(/\borigin:\([^)]+\)/, `origin:(${x_offset},0)`);
+                x_offset += width;
+                return `"${updated}"`;
+            }).join(' ');
+            return await runExec(`"${dpPath}" ${extend_args}`);
        }
-        else if (mode === 'extend') {
-            if (configStr) {
-                cmd = `"${binPath}" ${configStr}`;
-            }
+        return { success: false, error: `Unsupported display mode: ${mode}` };
+    });
+    // 6b. List Display Modes
+    electron_1.ipcMain.handle('native:list-display-modes', async () => {
+        if (os.platform() !== 'darwin')
+            return { success: false, error: 'Display control only supported on macOS' };
+        const dc_bin = electron_1.app.isPackaged
+            ? path.join(process.resourcesPath, 'bin', 'display_control')
+            : path.join(__dirname, '../../resources/bin/display_control');
+        if (!fs.existsSync(dc_bin)) {
+            return { success: false, error: 'display_control binary not found. Build via scripts/build-display-control.sh.' };
        }
-        if (cmd) {
-            return await runExec(cmd);
+        const result = await runExec(`"${dc_bin}" list-modes`);
+        if (!result.success || !result.stdout) {
+            return { success: false, error: result.error ?? 'list-modes returned no output' };
        }
-        return { success: false, error: 'Invalid mode or missing config' };
+        try {
+            const displays = JSON.parse(result.stdout);
+            return { success: true, displays };
+        }
+        catch (e) {
+            return { success: false, error: `Failed to parse list-modes output: ${e.message}`, raw: result.stdout };
+        }
+    });
+    // 6c. Set Display Mode
+    electron_1.ipcMain.handle('native:set-display-mode', async (event, { display_index, width, height, refresh_rate, hidpi }) => {
+        if (os.platform() !== 'darwin')
+            return { success: false, error: 'Display control only supported on macOS' };
+        const dc_bin = electron_1.app.isPackaged
+            ? path.join(process.resourcesPath, 'bin', 'display_control')
+            : path.join(__dirname, '../../resources/bin/display_control');
+        if (!fs.existsSync(dc_bin)) {
+            return { success: false, error: 'display_control binary not found. Build via scripts/build-display-control.sh.' };
+        }
+        let cmd = `"${dc_bin}" set-mode ${display_index} ${width} ${height}`;
+        if (refresh_rate)
+            cmd += ` --refresh ${refresh_rate}`;
+        if (hidpi === true)
+            cmd += ' --hidpi';
+        if (hidpi === false)
+            cmd += ' --no-hidpi';
+        return await runExec(cmd);
    });
    // 7. Update App
    electron_1.ipcMain.handle('native:update-app', async (event, { source, url, path: localPath }) => {
--- a/dist/main/system_handlers.js.map
+++ b/dist/main/system_handlers.js.map
--- a/dist/preload/index.js
+++ b/dist/preload/index.js
@@ -25,6 +25,8 @@ electron_1.contextBridge.exposeInMainWorld('aetherNative', {
    window_control: (args) => electron_1.ipcRenderer.invoke('native:window-control', args),
    manage_recording: (args) => electron_1.ipcRenderer.invoke('native:manage-recording', args),
    set_display_layout: (args) => electron_1.ipcRenderer.invoke('native:set-display-layout', args),
+    list_display_modes: () => electron_1.ipcRenderer.invoke('native:list-display-modes'),
+    set_display_mode: (args) => electron_1.ipcRenderer.invoke('native:set-display-mode', args),
    power_control: (args) => electron_1.ipcRenderer.invoke('native:power-control', args),
    open_external: (args) => electron_1.ipcRenderer.invoke('native:open-external', args),
 });
--- a/dist/preload/index.js.map
+++ b/dist/preload/index.js.map
@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/preload/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/preload/index.ts"],"names":[],"mappings":"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"}
--- a/documentation/TODO_AGENTS.md
+++ b/documentation/TODO_AGENTS.md
@@ -66,54 +66,83 @@

 ---

-## Pending Feature: set_display_layout — displayplacer Per-Device Config
+## set_display_layout — Setup & Status (updated 2026-05-20)

-**Background (added 2026-05-12, from Svelte-side LaunchProfile work):**
+**Primary approach: `display_control` (native CoreGraphics — no Homebrew required)**
+- Source: `scripts/display_control.m` (derived from OSIT MasterKey app, Ian Kohl 2019)
+- Build: run `scripts/build-display-control.sh` on a Mac (requires Xcode CLT only)
+- Output: `resources/bin/display_control` — commit this binary to the repo
+- Uses `CGConfigureDisplayMirrorOfDisplay` — same CoreGraphics API macOS uses internally
+- Supports 3+ displays; auto-detects all connected displays; no config string needed

-The Svelte Events Launcher (`launcher_file_cont.svelte`) now resolves a `LaunchProfile` per file extension and calls `native.set_display_layout({ mode })` before opening a presentation. The underlying handler in `src/main/system_handlers.ts` uses a bundled `displayplacer` macOS binary. The wiring is complete on both ends — but it **silently no-ops on every device** because `displayplacer` requires a per-machine `configStr` (the output of `displayplacer list` on *that specific Mac*) to identify the exact display UUIDs and pixel positions. Without it, `displayplacer` cannot apply any layout.
+**Fallback approach: `displayplacer` (requires `brew install displayplacer` on each venue Mac)**
+- Reference: [jakehilborn/displayplacer](https://github.com/jakehilborn/displayplacer)
+- Still used when `display_control` binary is not present
+- Also used for per-device `configStr` overrides (displayplacer-format strings in `event_device.data_json`)

-**What's needed:**
+**Current state (2026-05-20):**

-1. **Capture `configStr` per room Mac.** On each presentation Mac, run:
-   ```
-   displayplacer list
-   ```
-   This prints the current display configuration. Copy the full output for both the "extend" and "mirror" layouts (they differ in which display is primary and how they're positioned).
+- ✅ Correct `mirror_of_display:<uuid>` syntax used in displayplacer fallback
+- ✅ Failures logged to Electron console (`[Launcher] set_display_layout:`)
+- ✅ Display Mode toggle in Launcher config (Native OS section) — always visible
+- ✅ `display_control` binary built (universal x86_64 + arm64), committed to repo
+- ✅ **Idempotency** — `mirror` and `extend` both no-op with a clean message if already in the requested state (no display flicker)
+- ✅ **`list-modes`** — JSON array of all online displays + every usable `CGDisplayMode` (width, height, refresh, pixel size, HiDPI flag, is_current)
+- ✅ **`set-mode`** — sets resolution/refresh via `CGConfigureDisplayWithDisplayMode`; supports `--refresh`, `--hidpi`, `--no-hidpi`; auto-prefers HiDPI on built-in, non-HiDPI on externals
+- ✅ IPC handlers `native:list-display-modes` + `native:set-display-mode` wired through full bridge stack (system_handlers → preload → types → electron_relay)
+- ✅ Remote build script (`scripts/remote-build-display-control.sh`) — compiles on laptop-01 via SSH from Linux workstation; uses `ssh cat` pipe pattern (avoids scp space-in-username bug)

-2. **Store configs in the API.** The Svelte side reads device config from `event_device.data_json`. Store the captured strings there:
-   ```json
-   {
-     "displayplacer_config_extend": "<full configStr for extended layout>",
-     "displayplacer_config_mirror": "<full configStr for mirrored layout>"
-   }
-   ```
-   Admin UI to set these values already exists via the normal event_device edit flow. You can also set them directly via the V3 CRUD API (`PATCH /v3/crud/event_device/{id}/`).
+**To rebuild `display_control` after source changes:**
+```bash
+# From repo root on workstation (laptop-01 must be reachable):
+./scripts/remote-build-display-control.sh

-3. ✅ **`set_display_layout` in `src/main/system_handlers.ts` already accepts `configStr`.** Handler signature is `{ mode, configStr }` and uses it correctly — no change needed.
+# Or directly on a Mac:
+./scripts/build-display-control.sh

-4. ✅ **Electron relay (`src/preload/index.ts`) already forwards `configStr`** — args passed as-is. `AetherNativeBridge` type in `src/shared/types.ts` updated to include `set_display_layout` with correct signature (2026-05-12).
+# Test with a second display connected:
+./resources/bin/display_control status
+./resources/bin/display_control extend
+./resources/bin/display_control mirror
+./resources/bin/display_control list-modes
+./resources/bin/display_control set-mode 0 1920 1080
+./resources/bin/display_control set-mode 1 1920 1080 --refresh 60 --no-hidpi

-5. **Pass `configStr` from Svelte.** The Svelte call site in `launcher_file_cont.svelte` (Step 3 in `handle_open_file`) currently calls:
-   ```ts
-   await native.set_display_layout({ mode: profile.display_mode }).catch(() => {});
-   ```
-   It needs to be updated to thread `configStr` from `$ae_loc.native_device.data_json`:
-   ```ts
-   const cfg_key = profile.display_mode === 'mirror'
-       ? 'displayplacer_config_mirror'
-       : 'displayplacer_config_extend';
-   const configStr = ($ae_loc as any).native_device?.data_json?.[cfg_key] ?? null;
-   await native.set_display_layout({ mode: profile.display_mode, configStr }).catch(() => {});
-   ```
+# Commit:
+git add resources/bin/display_control
+git commit -m "build: update display_control binary (universal)"
+```

-**Contract already in place (Svelte side — no action needed):**
- `$ae_loc.native_device` is the `event_device` object loaded during native app bootstrap
- `data_json` is an open JSON field on that object
- `handle_open_file()` already calls `set_display_layout` at the right point — it just needs the configStr threaded through
+**Optional per-device override (displayplacer format, for edge cases):**
+For rooms where auto-detection produces the wrong result, store the raw configStr in `event_device.data_json`:
+```json
+{
+  "displayplacer_config_extend": "<output of displayplacer list in extended layout>",
+  "displayplacer_config_mirror": "<output of displayplacer list in mirrored layout>"
+}
+```
+`configStr` is passed from the Svelte call site and uses the displayplacer fallback path directly.

-**Resources:**
- displayplacer GitHub (usage + examples): https://github.com/jakehilborn/displayplacer
- `displayplacer list` — prints current layout as a re-runnable config string
- `displayplacer <configStr>` — applies layout; the configStr from `list` is what you pass back
- Current Electron handler: `src/main/system_handlers.ts` — find the `set_display_layout` IPC handler
- Svelte call site: `src/routes/events/[event_id]/(launcher)/launcher_file_cont.svelte` — Step 3 comment in `handle_open_file()`
+---
+
+## Future Ideas
+
+Capabilities worth adding as the Launcher matures. Roughly ordered by venue-day impact.
+
+### 1. Display reconfiguration events (push IPC)
+`CGDisplayRegisterReconfigurationCallback` fires when a display is connected or removed. Wrapping this in a `webContents.send('native:display-changed', payload)` push event would let the Svelte UI auto-mirror the moment a projector cable lands — eliminating the most common operator action during show setup. Currently the UI must poll `status` or the operator presses Mirror manually.
+
+### 2. Audio output routing
+When mirroring to a projector the audio output should follow. CoreAudio (`AudioObjectSetPropertyData` on `kAudioHardwarePropertyDefaultOutputDevice`) can switch the default output device programmatically. Candidate bridge method: `set_audio_output({device_name?, prefer_hdmi?})`. Could be called automatically as part of the mirror flow, or exposed as a standalone control.
+
+### 3. Battery / power status in telemetry
+`get_device_info` returns CPU and RAM but nothing about power. On venue MacBook Airs this matters operationally. IOKit (`IOPSCopyPowerSourcesInfo` / `IOPSGetPowerSourceDescription`) can surface: charge %, is-charging, time-remaining, health. Low-cost addition to the existing telemetry handler.
+
+### 4. Presentation state feedback
+`control_presentation` is fire-and-forget. AppleScript can query the current slide index and total slide count from both PowerPoint (`current slide index of active presentation`) and Keynote (`slide number of current slide of front document`). A `get_presentation_state()` bridge method returning `{ app, slide, total, presenting }` would let the Launcher UI show "Slide 7 of 42" — useful for operators monitoring multiple rooms.
+
+### 5. Push event channel (IPC renderer notifications)
+All bridge calls are currently request-response. Adding a `webContents.send` channel for unsolicited Electron → renderer events would unlock: display plug/unplug (#1 above), file download progress, network state changes, "presentation ended" detection. A thin `ipcMain.on('native:subscribe', ...)` registration pattern on the Electron side and a corresponding `ipcRenderer.on` listener in the preload would cover all use cases without breaking the existing handler structure.
+
+### 6. Kiosk / accidental-quit hardening
+A speaker or operator can accidentally Cmd+Q the launcher mid-presentation. `app.on('before-quit')` with either a confirmation dialog or an API-controlled lock flag (`event_device.data_json.kiosk_locked: true`) would prevent this. Can be toggled remotely — lock before the show, unlock after.
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "aether_app_native_electron",
-  "version": "1.0.0",
+  "version": "3.0.20",
  "description": "AE Native Launcher V3",
  "main": "dist/main/index.js",
  "scripts": {
@@ -10,7 +10,7 @@
    "build": "tsc",
    "watch": "tsc -w",
    "package:linux": "tsc && electron-packager . aether_launcher --platform=linux --arch=x64 --out=builds --overwrite --prune=true",
-    "package:mac": "tsc && electron-packager . aether_launcher --platform=darwin --arch=x64,arm64 --out=builds --overwrite --prune=true --icon=resources/img/osit_logo.icns"
+    "package:mac": "tsc && electron-packager . aether_launcher --platform=darwin --arch=x64,arm64 --out=builds --overwrite --prune=true --icon=resources/img/osit_logo.icns --extra-resource=resources/bin"
  },
  "devDependencies": {
    "@types/node": "^22.19.0",
--- a/resources/bin/display_control
+++ b/resources/bin/display_control
--- a/scripts/build-display-control.sh
+++ b/scripts/build-display-control.sh
@@ -0,0 +1,53 @@
+#!/bin/bash
+# scripts/build-display-control.sh
+# Compile the display_control binary for macOS.
+#
+# Requirements: Xcode Command Line Tools
+#   xcode-select --install
+#
+# Run this on a Mac. Commit the resulting binary to resources/bin/
+# so it is bundled into the packaged Electron app without any Homebrew dependency.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SRC="$SCRIPT_DIR/display_control.m"
+OUT_DIR="$REPO_ROOT/resources/bin"
+OUT_BIN="$OUT_DIR/display_control"
+
+if ! command -v clang &>/dev/null; then
+    echo "ERROR: clang not found."
+    echo "Install Xcode Command Line Tools:  xcode-select --install"
+    exit 1
+fi
+
+mkdir -p "$OUT_DIR"
+
+TMP_X86="$OUT_DIR/display_control_x86_64"
+TMP_ARM="$OUT_DIR/display_control_arm64"
+
+echo "Building display_control (x86_64)..."
+clang -arch x86_64 -framework Cocoa -framework Carbon \
+    -o "$TMP_X86" "$SRC"
+
+echo "Building display_control (arm64)..."
+clang -arch arm64 -framework Cocoa -framework Carbon \
+    -o "$TMP_ARM" "$SRC"
+
+echo "Linking universal binary..."
+lipo -create -output "$OUT_BIN" "$TMP_X86" "$TMP_ARM"
+rm "$TMP_X86" "$TMP_ARM"
+
+chmod +x "$OUT_BIN"
+
+echo ""
+echo "Built universal binary: $OUT_BIN"
+lipo -archs "$OUT_BIN"
+echo ""
+echo "Test it:"
+echo "  $OUT_BIN status"
+echo "  $OUT_BIN extend"
+echo "  $OUT_BIN mirror"
+echo ""
+echo "Once verified, commit resources/bin/display_control to the repo."
--- a/scripts/display_control.m
+++ b/scripts/display_control.m
@@ -0,0 +1,377 @@
+/*
+ * display_control.m
+ * Native macOS CLI for programmatic display mirror/extend control.
+ *
+ * Derived from the OSIT MasterKey app (LegacyUtilities.m, Ian Kohl 2019).
+ * Uses CoreGraphics APIs — no external dependencies (no displayplacer/Homebrew required).
+ *
+ * Build: run scripts/build-display-control.sh on a Mac (requires Xcode Command Line Tools)
+ * Usage: display_control <mirror|extend|status>
+ */
+
+#import <Cocoa/Cocoa.h>
+#include <Carbon/Carbon.h>
+#include <math.h>
+
+#define MAX_DISPLAYS 8
+#define MAX_MODES 256
+
+typedef struct { long src_index; size_t w, h, pw, ph; double refresh; } ModeEntry;
+
+static int mirror_displays(void) {
+    CGDirectDisplayID onlineDspys[MAX_DISPLAYS] = {0};
+    CGDisplayCount numOnline = 0;
+
+    CGGetOnlineDisplayList(MAX_DISPLAYS, onlineDspys, &numOnline);
+
+    if (numOnline < 2) {
+        fprintf(stderr, "No secondary display detected (%u online).\n", numOnline);
+        return 1;
+    }
+
+    CGDirectDisplayID mainID = CGMainDisplayID();
+
+    // Idempotency: if every secondary is already mirroring mainID, nothing to do.
+    CGDisplayCount alreadyMirrored = 0;
+    for (CGDisplayCount i = 0; i < numOnline; i++) {
+        if (onlineDspys[i] != mainID && CGDisplayMirrorsDisplay(onlineDspys[i]) == mainID)
+            alreadyMirrored++;
+    }
+    if (alreadyMirrored == numOnline - 1) {
+        printf("Displays already mirrored.\n");
+        return 0;
+    }
+
+    CGDisplayConfigRef config;
+    CGError err = CGBeginDisplayConfiguration(&config);
+    if (err != kCGErrorSuccess) {
+        fprintf(stderr, "CGBeginDisplayConfiguration failed: %d\n", err);
+        return 1;
+    }
+
+    BOOL any_configured = NO;
+    for (CGDisplayCount i = 0; i < numOnline; i++) {
+        if (onlineDspys[i] != mainID) {
+            err = CGConfigureDisplayMirrorOfDisplay(config, onlineDspys[i], mainID);
+            if (err != kCGErrorSuccess) {
+                fprintf(stderr, "CGConfigureDisplayMirrorOfDisplay failed: %d\n", err);
+                CGCancelDisplayConfiguration(config);
+                return 1;
+            }
+            any_configured = YES;
+        }
+    }
+
+    if (!any_configured) {
+        CGCancelDisplayConfiguration(config);
+        fprintf(stderr, "No secondary displays to mirror.\n");
+        return 1;
+    }
+
+    err = CGCompleteDisplayConfiguration(config, kCGConfigurePermanently);
+    if (err != kCGErrorSuccess) {
+        fprintf(stderr, "CGCompleteDisplayConfiguration failed: %d\n", err);
+        return 1;
+    }
+
+    printf("Mirrored %u display(s).\n", numOnline - 1);
+    return 0;
+}
+
+static int extend_displays(void) {
+    CGDirectDisplayID onlineDspys[MAX_DISPLAYS] = {0};
+    CGDirectDisplayID activeDspys[MAX_DISPLAYS] = {0};
+    CGDisplayCount numOnline = 0, numActive = 0;
+
+    CGGetOnlineDisplayList(MAX_DISPLAYS, onlineDspys, &numOnline);
+    CGGetActiveDisplayList(MAX_DISPLAYS, activeDspys, &numActive);
+
+    if (numOnline < 2) {
+        fprintf(stderr, "No secondary display detected (%u online).\n", numOnline);
+        return 1;
+    }
+
+    if (numActive >= numOnline) {
+        printf("Displays already extended.\n");
+        return 0;
+    }
+
+    CGDirectDisplayID mainID = CGMainDisplayID();
+
+    CGDisplayConfigRef config;
+    CGError err = CGBeginDisplayConfiguration(&config);
+    if (err != kCGErrorSuccess) {
+        fprintf(stderr, "CGBeginDisplayConfiguration failed: %d\n", err);
+        return 1;
+    }
+
+    for (CGDisplayCount i = 0; i < numOnline; i++) {
+        if (onlineDspys[i] != mainID) {
+            // kCGNullDirectDisplay as master = un-mirror (extend)
+            err = CGConfigureDisplayMirrorOfDisplay(config, onlineDspys[i], kCGNullDirectDisplay);
+            if (err != kCGErrorSuccess) {
+                fprintf(stderr, "CGConfigureDisplayMirrorOfDisplay(null) failed: %d\n", err);
+                CGCancelDisplayConfiguration(config);
+                return 1;
+            }
+        }
+    }
+
+    err = CGCompleteDisplayConfiguration(config, kCGConfigurePermanently);
+    if (err != kCGErrorSuccess) {
+        fprintf(stderr, "CGCompleteDisplayConfiguration failed: %d\n", err);
+        return 1;
+    }
+
+    printf("Displays extended.\n");
+    return 0;
+}
+
+static void print_status(void) {
+    CGDirectDisplayID onlineDspys[MAX_DISPLAYS] = {0};
+    CGDirectDisplayID activeDspys[MAX_DISPLAYS] = {0};
+    CGDisplayCount numOnline = 0, numActive = 0;
+
+    CGGetOnlineDisplayList(MAX_DISPLAYS, onlineDspys, &numOnline);
+    CGGetActiveDisplayList(MAX_DISPLAYS, activeDspys, &numActive);
+
+    printf("online=%u active=%u %s\n",
+           numOnline, numActive,
+           (numOnline > 1 && numActive < numOnline) ? "mirrored" : "extended");
+}
+
+// ── list-modes ──────────────────────────────────────────────────────────────
+// Outputs a JSON array describing every online display and its available modes.
+
+static void list_modes(void) {
+    CGDirectDisplayID displays[MAX_DISPLAYS];
+    CGDisplayCount count = 0;
+    CGGetOnlineDisplayList(MAX_DISPLAYS, displays, &count);
+    CGDirectDisplayID mainID = CGMainDisplayID();
+
+    printf("[\n");
+    for (CGDisplayCount d = 0; d < count; d++) {
+        CGDirectDisplayID dID = displays[d];
+        CGDisplayModeRef currentMode = CGDisplayCopyDisplayMode(dID);
+        size_t curW  = CGDisplayModeGetWidth(currentMode);
+        size_t curH  = CGDisplayModeGetHeight(currentMode);
+        double curR  = CGDisplayModeGetRefreshRate(currentMode);
+        size_t curPW = CGDisplayModeGetPixelWidth(currentMode);
+        size_t curPH = CGDisplayModeGetPixelHeight(currentMode);
+
+        // Include HiDPI duplicate entries so scaled modes are visible.
+        CFStringRef  optKeys[] = { kCGDisplayShowDuplicateLowResolutionModes };
+        CFBooleanRef optVals[] = { kCFBooleanTrue };
+        CFDictionaryRef opts = CFDictionaryCreate(NULL,
+            (const void **)optKeys, (const void **)optVals, 1,
+            &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks);
+        CFArrayRef allModes = CGDisplayCopyAllDisplayModes(dID, opts);
+        CFRelease(opts);
+        CFIndex total = CFArrayGetCount(allModes);
+
+        // Collect usable modes first so we know the count for comma handling.
+        ModeEntry usable[MAX_MODES];
+        int usable_count = 0;
+        for (CFIndex m = 0; m < total && usable_count < MAX_MODES; m++) {
+            CGDisplayModeRef mode = (CGDisplayModeRef)CFArrayGetValueAtIndex(allModes, m);
+            if (!CGDisplayModeIsUsableForDesktopGUI(mode)) continue;
+            usable[usable_count++] = (ModeEntry){
+                .src_index = (long)m,
+                .w = CGDisplayModeGetWidth(mode),
+                .h = CGDisplayModeGetHeight(mode),
+                .pw = CGDisplayModeGetPixelWidth(mode),
+                .ph = CGDisplayModeGetPixelHeight(mode),
+                .refresh = CGDisplayModeGetRefreshRate(mode)
+            };
+        }
+
+        printf("  {\n");
+        printf("    \"index\": %u,\n", d);
+        printf("    \"id\": %u,\n", (unsigned int)dID);
+        printf("    \"is_main\": %s,\n", dID == mainID ? "true" : "false");
+        printf("    \"current_width\": %zu,\n", curW);
+        printf("    \"current_height\": %zu,\n", curH);
+        printf("    \"current_refresh\": %.2f,\n", curR);
+        printf("    \"current_pixel_width\": %zu,\n", curPW);
+        printf("    \"current_pixel_height\": %zu,\n", curPH);
+        printf("    \"modes\": [\n");
+        for (int i = 0; i < usable_count; i++) {
+            ModeEntry *e = &usable[i];
+            int isCurrent = (e->w == curW && e->h == curH &&
+                             e->pw == curPW && e->ph == curPH &&
+                             fabs(e->refresh - curR) < 0.5);
+            printf("      {\"index\":%ld,\"width\":%zu,\"height\":%zu,"
+                   "\"refresh\":%.2f,\"pixel_width\":%zu,\"pixel_height\":%zu,"
+                   "\"hidpi\":%s,\"is_current\":%s}%s\n",
+                   e->src_index, e->w, e->h, e->refresh, e->pw, e->ph,
+                   (e->pw > e->w || e->ph > e->h) ? "true" : "false",
+                   isCurrent ? "true" : "false",
+                   (i < usable_count - 1) ? "," : "");
+        }
+        printf("    ]\n");
+        printf("  }%s\n", (d < count - 1) ? "," : "");
+
+        CGDisplayModeRelease(currentMode);
+        CFRelease(allModes);
+    }
+    printf("]\n");
+}
+
+// ── set-mode ─────────────────────────────────────────────────────────────────
+// display_idx : index from list-modes (0 = primary, 1 = first external, ...)
+// req_w/h     : logical width × height (what macOS calls "looks like X×Y")
+// req_refresh : 0 = pick highest available; >0 = must be within 1 Hz
+// force_hidpi : 1 = HiDPI only; -1 = non-HiDPI only; 0 = auto
+//               auto prefers HiDPI on the built-in, non-HiDPI on externals
+
+static int set_mode(int display_idx, size_t req_w, size_t req_h,
+                    double req_refresh, int force_hidpi) {
+    CGDirectDisplayID displays[MAX_DISPLAYS];
+    CGDisplayCount count = 0;
+    CGGetOnlineDisplayList(MAX_DISPLAYS, displays, &count);
+
+    if (display_idx < 0 || (CGDisplayCount)display_idx >= count) {
+        fprintf(stderr, "Display index %d out of range (0..%u).\n",
+                display_idx, count > 0 ? count - 1 : 0);
+        return 1;
+    }
+
+    CGDirectDisplayID dID = displays[display_idx];
+    int isMain = (dID == CGMainDisplayID());
+
+    CFStringRef  optKeys[] = { kCGDisplayShowDuplicateLowResolutionModes };
+    CFBooleanRef optVals[] = { kCFBooleanTrue };
+    CFDictionaryRef opts = CFDictionaryCreate(NULL,
+        (const void **)optKeys, (const void **)optVals, 1,
+        &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks);
+    CFArrayRef allModes = CGDisplayCopyAllDisplayModes(dID, opts);
+    CFRelease(opts);
+    CFIndex total = CFArrayGetCount(allModes);
+
+    CGDisplayModeRef bestMode = NULL;
+    double bestRefresh = -1.0;
+    int bestScore = -1;  // higher = more preferred
+
+    for (CFIndex m = 0; m < total; m++) {
+        CGDisplayModeRef mode = (CGDisplayModeRef)CFArrayGetValueAtIndex(allModes, m);
+        if (!CGDisplayModeIsUsableForDesktopGUI(mode)) continue;
+
+        size_t w = CGDisplayModeGetWidth(mode);
+        size_t h = CGDisplayModeGetHeight(mode);
+        if (w != req_w || h != req_h) continue;
+
+        double refresh = CGDisplayModeGetRefreshRate(mode);
+        if (req_refresh > 0.0 && fabs(refresh - req_refresh) > 1.0) continue;
+
+        size_t pw = CGDisplayModeGetPixelWidth(mode);
+        int isHiDPI = (pw > w);
+
+        if (force_hidpi ==  1 && !isHiDPI) continue;
+        if (force_hidpi == -1 &&  isHiDPI) continue;
+
+        // Score: prefer HiDPI on main display, non-HiDPI on external.
+        int score = (force_hidpi == 0)
+            ? ((isMain && isHiDPI) || (!isMain && !isHiDPI)) ? 1 : 0
+            : 0;
+
+        if (bestMode == NULL || score > bestScore ||
+            (score == bestScore && refresh > bestRefresh)) {
+            bestMode    = mode;
+            bestRefresh = refresh;
+            bestScore   = score;
+        }
+    }
+
+    if (!bestMode) {
+        fprintf(stderr, "No matching mode for display %d: %zux%zu",
+                display_idx, req_w, req_h);
+        if (req_refresh > 0.0) fprintf(stderr, " @%.0fHz", req_refresh);
+        if (force_hidpi ==  1) fprintf(stderr, " [HiDPI required]");
+        if (force_hidpi == -1) fprintf(stderr, " [non-HiDPI required]");
+        fprintf(stderr, ".\nRun: display_control list-modes\n");
+        CFRelease(allModes);
+        return 1;
+    }
+
+    size_t setW  = CGDisplayModeGetWidth(bestMode);
+    size_t setH  = CGDisplayModeGetHeight(bestMode);
+    double setR  = CGDisplayModeGetRefreshRate(bestMode);
+    size_t setPW = CGDisplayModeGetPixelWidth(bestMode);
+    size_t setPH = CGDisplayModeGetPixelHeight(bestMode);
+
+    CGDisplayConfigRef config;
+    CGError err = CGBeginDisplayConfiguration(&config);
+    if (err != kCGErrorSuccess) {
+        fprintf(stderr, "CGBeginDisplayConfiguration failed: %d\n", err);
+        CFRelease(allModes);
+        return 1;
+    }
+
+    err = CGConfigureDisplayWithDisplayMode(config, dID, bestMode, NULL);
+    if (err != kCGErrorSuccess) {
+        fprintf(stderr, "CGConfigureDisplayWithDisplayMode failed: %d\n", err);
+        CGCancelDisplayConfiguration(config);
+        CFRelease(allModes);
+        return 1;
+    }
+
+    err = CGCompleteDisplayConfiguration(config, kCGConfigurePermanently);
+    if (err != kCGErrorSuccess) {
+        fprintf(stderr, "CGCompleteDisplayConfiguration failed: %d\n", err);
+        CFRelease(allModes);
+        return 1;
+    }
+
+    printf("Set display %d to %zux%zu @%.0fHz (pixel %zux%zu).\n",
+           display_idx, setW, setH, setR, setPW, setPH);
+    CFRelease(allModes);
+    return 0;
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+int main(int argc, const char * argv[]) {
+    @autoreleasepool {
+        if (argc < 2) {
+            fprintf(stderr, "Usage: display_control <mirror|extend|status|list-modes|set-mode>\n");
+            return 1;
+        }
+
+        const char *cmd = argv[1];
+
+        if (strcmp(cmd, "mirror") == 0) {
+            return mirror_displays();
+        } else if (strcmp(cmd, "extend") == 0) {
+            return extend_displays();
+        } else if (strcmp(cmd, "status") == 0) {
+            print_status();
+            return 0;
+        } else if (strcmp(cmd, "list-modes") == 0) {
+            list_modes();
+            return 0;
+        } else if (strcmp(cmd, "set-mode") == 0) {
+            if (argc < 5) {
+                fprintf(stderr, "Usage: display_control set-mode <display_index> <width> <height> [--refresh <hz>] [--hidpi] [--no-hidpi]\n");
+                return 1;
+            }
+            int    display_idx = atoi(argv[2]);
+            size_t req_w       = (size_t)atol(argv[3]);
+            size_t req_h       = (size_t)atol(argv[4]);
+            double req_refresh = 0.0;
+            int    force_hidpi = 0;
+            for (int i = 5; i < argc; i++) {
+                if (strcmp(argv[i], "--refresh") == 0 && i + 1 < argc) {
+                    req_refresh = atof(argv[++i]);
+                } else if (strcmp(argv[i], "--hidpi") == 0) {
+                    force_hidpi = 1;
+                } else if (strcmp(argv[i], "--no-hidpi") == 0) {
+                    force_hidpi = -1;
+                }
+            }
+            return set_mode(display_idx, req_w, req_h, req_refresh, force_hidpi);
+        } else {
+            fprintf(stderr, "Unknown command: %s\nUsage: display_control <mirror|extend|status|list-modes|set-mode>\n", cmd);
+            return 1;
+        }
+    }
+}
--- a/scripts/remote-build-display-control.sh
+++ b/scripts/remote-build-display-control.sh
@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# scripts/remote-build-display-control.sh
+# Build the display_control universal binary on a remote Mac via SSH,
+# then pull the result back to resources/bin/display_control.
+#
+# Use this from the Linux workstation when you don't have a Mac locally.
+# The target Mac must have Xcode Command Line Tools installed.
+#
+# USAGE:
+#   ./scripts/remote-build-display-control.sh              # uses default Mac (laptop 01)
+#   ./scripts/remote-build-display-control.sh 192.168.32.102
+#
+# The default IP is laptop 01 — the designated build Mac.
+# Change DEFAULT_IP below if Xcode moves to a different laptop.
+#
+# SSH key must already be installed on the target:
+#   ssh-copy-id "speaker ready"@192.168.32.101
+
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SRC="$SCRIPT_DIR/display_control.m"
+OUT_BIN="$REPO_ROOT/resources/bin/display_control"
+
+SSH_USER="speaker ready"
+DEFAULT_IP="192.168.32.101"
+IP="${1:-$DEFAULT_IP}"
+
+REMOTE_TMP="/tmp/ae_display_control_build"
+
+echo "═══════════════════════════════════════════════"
+echo "  Remote build: display_control"
+echo "  Build Mac: $SSH_USER @ $IP"
+echo "═══════════════════════════════════════════════"
+
+# ── Step 1: Copy source to remote ────────────────────────────────────────────
+
+echo ""
+echo "Step 1/4 — Copying source to $IP..."
+ssh "$SSH_USER@$IP" "mkdir -p $REMOTE_TMP"
+ssh "$SSH_USER@$IP" "cat > $REMOTE_TMP/display_control.m" < "$SRC"
+
+# ── Step 2: Build universal binary on remote ──────────────────────────────────
+
+echo ""
+echo "Step 2/4 — Building on $IP..."
+ssh "$SSH_USER@$IP" bash << 'ENDSSH'
+set -e
+REMOTE_TMP="/tmp/ae_display_control_build"
+SRC="$REMOTE_TMP/display_control.m"
+TMP_X86="$REMOTE_TMP/display_control_x86_64"
+TMP_ARM="$REMOTE_TMP/display_control_arm64"
+OUT="$REMOTE_TMP/display_control"
+
+echo "  Compiling x86_64..."
+clang -arch x86_64 -framework Cocoa -framework Carbon -o "$TMP_X86" "$SRC"
+
+echo "  Compiling arm64..."
+clang -arch arm64 -framework Cocoa -framework Carbon -o "$TMP_ARM" "$SRC"
+
+echo "  Linking universal binary..."
+lipo -create -output "$OUT" "$TMP_X86" "$TMP_ARM"
+rm "$TMP_X86" "$TMP_ARM"
+chmod +x "$OUT"
+
+echo "  Archs: $(lipo -archs "$OUT")"
+ENDSSH
+
+# ── Step 3: Pull binary back ──────────────────────────────────────────────────
+
+echo ""
+echo "Step 3/4 — Pulling binary to resources/bin/..."
+mkdir -p "$(dirname "$OUT_BIN")"
+ssh "$SSH_USER@$IP" "cat $REMOTE_TMP/display_control" > "$OUT_BIN"
+chmod +x "$OUT_BIN"
+
+# ── Step 4: Clean up remote ───────────────────────────────────────────────────
+
+echo ""
+echo "Step 4/4 — Cleaning up remote..."
+ssh "$SSH_USER@$IP" "rm -rf $REMOTE_TMP"
+
+# ── Done ──────────────────────────────────────────────────────────────────────
+
+echo ""
+echo "═══════════════════════════════════════════════"
+echo "  Built: $OUT_BIN"
+file "$OUT_BIN"
+echo ""
+echo "  If both archs shown above, you're good:"
+echo "    git add resources/bin/display_control"
+echo "    git commit -m \"build: update display_control binary (universal)\""
+echo "═══════════════════════════════════════════════"
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -19,8 +19,8 @@ async function createWindow() {
  }

  mainWindow = new BrowserWindow({
-    width: 1600,
-    height: 900,
+    width: 1280,
+    height: 800,
    title: 'OSIT Aether Launcher (Native)',
    webPreferences: {
      preload: path.join(__dirname, '../preload/index.js'),
@@ -29,6 +29,10 @@ async function createWindow() {
    },
  });

+  // Let the native window manager maximize — more reliable than using screen.workArea,
+  // which Electron under-reports on KDE and other Linux DEs.
+  mainWindow.maximize();
+
  let targetUrl = 'http://demo.localhost:5173';
  if (cachedFullConfig && cachedFullConfig.native_device) {
    const device = cachedFullConfig.native_device;
@@ -55,15 +59,28 @@ registerShellHandlers();
 registerFileHandlers();
 registerSystemHandlers();

-app.on('ready', createWindow);
+// Single instance lock — if another instance is already running, focus it and quit.
+const gotTheLock = app.requestSingleInstanceLock();
+if (!gotTheLock) {
+  app.quit();
+} else {
+  app.on('second-instance', () => {
+    if (mainWindow) {
+      if (mainWindow.isMinimized()) mainWindow.restore();
+      mainWindow.focus();
+    }
+  });

-app.on('window-all-closed', () => {
-  if (process.platform !== 'darwin') app.quit();
-});
+  app.on('ready', createWindow);

-app.on('activate', () => {
-  if (mainWindow === null) createWindow();
-});
+  app.on('window-all-closed', () => {
+    if (process.platform !== 'darwin') app.quit();
+  });
+
+  app.on('activate', () => {
+    if (mainWindow === null) createWindow();
+  });
+}

 ipcMain.handle('get-seed-config', async () => cachedSeed || await loadSeedConfig());
 ipcMain.handle('get-device-config', async () => cachedFullConfig);
--- a/src/main/shell_handlers.ts
+++ b/src/main/shell_handlers.ts
@@ -171,65 +171,115 @@ end tell

  ipcMain.handle('native:list-tools', async () => {
    return [
+      // --- Config & Info ---
+      {
+        name: 'get_device_config',
+        description: 'Returns hydrated device config injected at startup from seed.json + API.',
+        params: {}
+      },
+      {
+        name: 'get_device_info',
+        description: 'Returns OS metadata: platform, hostname, IPs, CPU count, free RAM, home/tmp paths.',
+        params: {}
+      },
+      // --- File Cache ---
+      {
+        name: 'check_cache',
+        description: 'Checks if a file exists in the hashed cache. verify_hash:true re-hashes to confirm integrity.',
+        params: { cache_root: 'string', hash: 'string', hash_prefix_length: 'number (optional, default 2)', verify_hash: 'boolean (optional)' }
+      },
+      {
+        name: 'download_to_cache',
+        description: 'Streams a file from the API into the hashed cache with SHA-256 integrity check. Cleans stale .tmp files older than 5 min.',
+        params: { url: 'string', cache_root: 'string', hash: 'string', api_key: 'string', account_id: 'string', hash_prefix_length: 'number (optional, default 2)' }
+      },
+      {
+        name: 'copy_from_cache_to_temp',
+        description: 'Preferred primitive. Copies a cached file to temp with its original filename. Returns { success, path }. Caller decides what to do next.',
+        params: { cache_root: 'string', hash: 'string', temp_root: 'string', filename: 'string', hash_prefix_length: 'number (optional, default 2)' }
+      },
+      {
+        name: 'launch_from_cache',
+        description: 'Combines copy_from_cache_to_temp + execute. Runs native_template after copying — AppleScript string with {{path}} placeholder, or "shell:<cmd>" prefix. Returns error if native_template is null.',
+        params: { cache_root: 'string', hash: 'string', temp_root: 'string', filename: 'string', hash_prefix_length: 'number (optional)', native_template: 'string | null' }
+      },
+      // --- Shell & OS ---
      {
        name: 'open_folder',
-        description: 'Opens a directory in the OS file explorer (Finder/Files/Explorer).',
+        description: 'Opens a directory in the OS file explorer (Finder on macOS).',
        params: { path: 'string' }
      },
      {
        name: 'run_cmd',
-        description: 'Executes an asynchronous shell command with a timeout.',
-        params: { cmd: 'string', timeout: 'number (optional)' }
+        description: 'Async shell command execution with timeout.',
+        params: { cmd: 'string', timeout: 'number (optional, default 30000ms)' }
      },
      {
        name: 'run_cmd_sync',
-        description: 'Executes a synchronous shell command.',
+        description: 'Synchronous shell command execution.',
        params: { cmd: 'string' }
      },
      {
        name: 'run_osascript',
-        description: 'Executes a raw AppleScript string (macOS only).',
+        description: 'Hardened AppleScript executor — writes to temp .scpt file, handles multi-line scripts and paths with special characters. macOS only.',
        params: { script: 'string' }
      },
      {
        name: 'kill_processes',
-        description: 'Forcefully terminates processes by name.',
+        description: 'Terminates processes by name. macOS/Linux: pkill -f. Windows: taskkill /F.',
        params: { process_name_li: 'string[]' }
      },
      {
        name: 'open_local_file_v2',
-        description: 'Opens a local file using the default OS handler.',
-        params: { filePath: 'string' }
+        description: 'Opens a file with its default OS application via shell.openPath.',
+        params: { path: 'string' }
      },
+      {
+        name: 'open_external',
+        description: 'Opens a URL in Chrome, Firefox, or the system default browser.',
+        params: { url: 'string', app: 'chrome | firefox | default (optional)' }
+      },
+      // --- Presentations ---
      {
        name: 'launch_presentation',
-        description: 'Phase 5: Specialized launcher for PowerPoint, Keynote, and LibreOffice with auto-focus.',
-        params: { path: 'string', app: 'default|powerpoint|keynote' }
+        description: 'Platform-aware launcher for PowerPoint, Keynote, LibreOffice. Resolves [home]/[tmp] placeholders. Hardened AppleScript (2026-05-11). Prefer copy_from_cache_to_temp + run_osascript for new flows.',
+        params: { path: 'string', app: 'default | powerpoint | keynote (optional)', os_platform: 'string (optional)' }
      },
      {
        name: 'control_presentation',
-        description: 'Phase 5: Remote navigation for active slideshows.',
-        params: { app: 'powerpoint|keynote', action: 'next|prev|start|stop' }
+        description: 'Slide navigation for active PowerPoint or Keynote via AppleScript. macOS only.',
+        params: { app: 'powerpoint | keynote', action: 'next | prev | start | stop' }
+      },
+      // --- System Management ---
+      {
+        name: 'set_wallpaper',
+        description: 'Sets desktop wallpaper. Downloads from url (cached to ~/Library/Caches/OSIT/wallpaper/) or applies local path. url_external targets projector/second display separately. macOS only in production.',
+        params: { path: 'string (optional)', url: 'string (optional)', url_external: 'string (optional)', display: 'all | primary | external (optional, default all)', api_key: 'string (optional)', account_id: 'string (optional)' }
      },
      {
-        name: 'check_cache',
-        description: 'Checks if a file exists in the local organized cache.',
-        params: { cache_root: 'string', hash: 'string', hash_prefix_length: 'number' }
+        name: 'set_display_layout',
+        description: 'Mirror or extend displays via bundled displayplacer. macOS only. Auto-detects displays when no configStr given; configStr is an optional manual override.',
+        params: { mode: 'mirror | extend', configStr: 'string (optional)' }
      },
      {
-        name: 'download_to_cache',
-        description: 'Downloads a file from the API directly into the native cache.',
-        params: { url: 'string', cache_root: 'string', hash: 'string', api_key: 'string', account_id: 'string' }
+        name: 'window_control',
+        description: 'Electron window management.',
+        params: { action: 'maximize | unmaximize | minimize | restore | close | fullscreen | kiosk | devtools | reload', value: 'boolean (optional, used by fullscreen/kiosk/devtools)' }
      },
      {
-        name: 'launch_from_cache',
-        description: 'Atomic operation: Copies file from cache to temp with original name and launches via specialized handler.',
-        params: { cache_root: 'string', hash: 'string', temp_root: 'string', filename: 'string' }
+        name: 'power_control',
+        description: 'Shutdown, reboot, or sleep the host machine. macOS + Linux. May require sudo for shutdown/reboot.',
+        params: { action: 'shutdown | reboot | sleep' }
      },
      {
-        name: 'get_device_info',
-        description: 'Returns hardware and OS metadata (CPUs, RAM, IP addresses, Hostname).',
-        params: {}
+        name: 'manage_recording',
+        description: 'Screen recording via bundled aperture binary. macOS only.',
+        params: { action: 'start | stop | status', options: '{ fps?, audioDeviceId?, output? } (optional)' }
+      },
+      {
+        name: 'update_app',
+        description: 'STUB: Downloads update package but does not install. Not functional.',
+        params: { source: 'url | file', url: 'string (optional)', path: 'string (optional)' }
      }
    ];
  });
--- a/src/main/system_handlers.ts
+++ b/src/main/system_handlers.ts
@@ -23,7 +23,7 @@ const runExec = (cmd: string): Promise<{ success: boolean; stdout?: string; stde
 let recordingProcess: any = null;

 export function registerSystemHandlers() {
-  
+
  // 1. Window Control
  ipcMain.handle('native:window-control', async (event, { action, value }) => {
    const win = BrowserWindow.fromWebContents(event.sender);
@@ -35,7 +35,7 @@ export function registerSystemHandlers() {
      case 'minimize': win.minimize(); break;
      case 'restore': win.restore(); break;
      case 'close': win.close(); break;
-      case 'devtools': 
+      case 'devtools':
        if (value) win.webContents.openDevTools();
        else win.webContents.closeDevTools();
        break;
@@ -48,18 +48,173 @@ export function registerSystemHandlers() {
  });

  // 2. Set Wallpaper
-  ipcMain.handle('native:set-wallpaper', async (event, { path: imagePath }) => {
-    const cleanPath = expandPath(imagePath);
-    if (!fs.existsSync(cleanPath)) return { success: false, error: 'Image file not found' };
+  // Supports local path OR URL download. URL images are saved to a stable cache dir
+  // so macOS can reference them persistently after reboot.
+  // display: 'all' (default) | 'primary' (built-in) | 'external' (projector/second screen)
+  // url_external: optional second URL for the external display only.
+  ipcMain.handle('native:set-wallpaper', async (event, {
+    path: imagePath,
+    url,
+    url_external,
+    display = 'all',
+    api_key,
+    account_id
+  }: {
+    path?: string;
+    url?: string;
+    url_external?: string;
+    display?: 'all' | 'primary' | 'external';
+    api_key?: string;
+    account_id?: string;
+  }) => {
+    // Cache dir: ~/Library/Caches/OSIT/wallpaper on macOS, ~/.cache/osit/wallpaper on Linux.
+    // Using a stable path means macOS keeps the reference across reboots.
+    const wallpaper_cache_dir = os.platform() === 'darwin'
+      ? path.join(os.homedir(), 'Library', 'Caches', 'OSIT', 'wallpaper')
+      : path.join(os.homedir(), '.cache', 'osit', 'wallpaper');
+
+    async function download_wallpaper_image(image_url: string, basename: string): Promise<{ success: boolean; path?: string; error?: string }> {
+      if (!fs.existsSync(wallpaper_cache_dir)) {
+        fs.mkdirSync(wallpaper_cache_dir, { recursive: true });
+      }
+
+      // Infer extension from URL path, fall back to .jpg
+      let ext = '.jpg';
+      try {
+        const url_path = new URL(image_url).pathname;
+        const inferred = path.extname(url_path).toLowerCase();
+        if (['.jpg', '.jpeg', '.png', '.webp'].includes(inferred)) {
+          ext = inferred === '.jpeg' ? '.jpg' : inferred;
+        }
+      } catch {}
+
+      const dest_path = path.join(wallpaper_cache_dir, basename + ext);
+
+      const headers: Record<string, string> = {};
+      if (api_key) headers['x-aether-api-key'] = api_key;
+      if (account_id) headers['x-account-id'] = account_id;
+
+      try {
+        const response = await axios({ method: 'get', url: image_url, responseType: 'stream', headers });
+        const content_type = (response.headers['content-type'] ?? '') as string;
+        if (!content_type.startsWith('image/')) {
+          response.data.destroy();
+          return { success: false, error: `URL did not return an image (Content-Type: ${content_type})` };
+        }
+
+        const writer = fs.createWriteStream(dest_path);
+        response.data.pipe(writer);
+        await new Promise<void>((resolve, reject) => {
+          writer.on('finish', resolve);
+          writer.on('error', reject);
+        });
+        const file_size = fs.statSync(dest_path).size;
+        if (file_size === 0) {
+          try { fs.unlinkSync(dest_path); } catch {}
+          return { success: false, error: 'Wallpaper download incomplete (0 bytes)' };
+        }
+        return { success: true, path: dest_path };
+      } catch (e: any) {
+        return { success: false, error: `Wallpaper download failed: ${e.message}` };
+      }
+    }
+
+    // HARDENED: write AppleScript to a temp file, same pattern as native:run-osascript.
+    // The old osascript -e approach breaks on paths with spaces or special characters.
+    async function apply_mac_wallpaper(img_path: string, display_target: 'all' | 'primary' | 'external'): Promise<{ success: boolean; stdout?: string; stderr?: string; error?: string }> {
+      const escaped = img_path.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+      let script: string;
+      if (display_target === 'primary') {
+        script = `tell application "System Events"\n\ttell desktop 1\n\t\tset picture to "${escaped}"\n\tend tell\nend tell`;
+      } else if (display_target === 'external') {
+        script = `tell application "System Events"\n\ttell desktop 2\n\t\tset picture to "${escaped}"\n\tend tell\nend tell`;
+      } else {
+        script = `tell application "System Events"\n\ttell every desktop\n\t\tset picture to "${escaped}"\n\tend tell\nend tell`;
+      }
+
+      const script_path = path.join(os.tmpdir(), `ae_wallpaper_${Date.now()}.scpt`);
+      fs.writeFileSync(script_path, script, 'utf-8');
+      try {
+        return await runExec(`osascript "${script_path}"`);
+      } finally {
+        try { fs.unlinkSync(script_path); } catch {}
+      }
+    }

    if (os.platform() === 'darwin') {
-      const script = `tell application "System Events" to set picture of every desktop to "${cleanPath}"`;
-      return await runExec(`osascript -e '${script}'`);
-    } else if (os.platform() === 'linux') {
-      // Gnome/Ubuntu default
-      return await runExec(`gsettings set org.gnome.desktop.background picture-uri "file://${cleanPath}"`);
+      // Resolve primary image path
+      let primary_path: string | null = null;
+
+      if (imagePath) {
+        const clean = expandPath(imagePath);
+        if (!fs.existsSync(clean)) return { success: false, error: 'Image file not found' };
+        primary_path = clean;
+      } else if (url) {
+        const result = await download_wallpaper_image(url, 'wallpaper_primary');
+        if (!result.success || !result.path) return { success: false, error: result.error };
+        primary_path = result.path;
+      }
+
+      if (!primary_path && url_external && display === 'external') {
+        const ext_result = await download_wallpaper_image(url_external, 'wallpaper_external');
+        if (!ext_result.success || !ext_result.path) return { success: false, error: ext_result.error };
+        return await apply_mac_wallpaper(ext_result.path, 'external');
+      }
+
+      if (!primary_path) return { success: false, error: 'No image source provided' };
+
+      if (url_external) {
+        // Different images for each display: set primary display first, then external
+        const primary_result = await apply_mac_wallpaper(primary_path, 'primary');
+        if (!primary_result.success) return primary_result;
+
+        const ext_result = await download_wallpaper_image(url_external, 'wallpaper_external');
+        if (!ext_result.success || !ext_result.path) return { success: false, error: ext_result.error };
+        return await apply_mac_wallpaper(ext_result.path, 'external');
+      } else {
+        return await apply_mac_wallpaper(primary_path, display);
+      }
    }
-    
+
+    if (os.platform() === 'linux') {
+      // Dev test mode: never touch the desktop on Linux. Running gsettings during
+      // development would reset the dev workstation monitors on every test cycle.
+      // Return what would have run so the Svelte side can show a debug popup.
+      const would_run: string[] = [];
+      const cache_dir = wallpaper_cache_dir;
+
+      if (!imagePath && !url && !url_external) {
+        return { success: false, error: 'No image source provided' };
+      }
+
+      if (imagePath) {
+        const clean = expandPath(imagePath);
+        if (!fs.existsSync(clean)) return { success: false, error: 'Image file not found' };
+      }
+
+      if (url) would_run.push(`download: ${url}\n  → ${path.join(cache_dir, 'wallpaper_primary.jpg')}`);
+      if (url_external) would_run.push(`download: ${url_external}\n  → ${path.join(cache_dir, 'wallpaper_external.jpg')}`);
+
+      if (imagePath) {
+        would_run.push(`gsettings set org.gnome.desktop.background picture-uri "file://${expandPath(imagePath)}"`);
+      } else if (url) {
+        would_run.push(`gsettings set org.gnome.desktop.background picture-uri "file://${path.join(cache_dir, 'wallpaper_primary.jpg')}"`);
+      }
+      if (url_external) {
+        would_run.push(`(external display: gsettings has no per-display wallpaper support)`);
+      }
+
+      return {
+        success: true,
+        linux_test_mode: true,
+        platform: 'linux',
+        display,
+        url: url ?? null,
+        url_external: url_external ?? null,
+        would_run
+      };
+    }
+
    return { success: false, error: 'Platform not supported' };
  });

@@ -81,8 +236,8 @@ export function registerSystemHandlers() {
    }

    if (!cmd) return { success: false, error: 'Action not supported' };
-    
-    // NOTE: These commands often require root. 
+
+    // NOTE: These commands often require root.
    // For a kiosk, you might configure sudoers to allow this specific command without password.
    return await runExec(cmd);
  });
@@ -102,7 +257,7 @@ export function registerSystemHandlers() {
            return await runExec(`firefox "${url}"`);
        }
    }
-    
+
    // Default system handler
    await shell.openExternal(url);
    return { success: true };
@@ -111,30 +266,30 @@ export function registerSystemHandlers() {
  // 5. Manage Recording (Aperture Wrapper)
  ipcMain.handle('native:manage-recording', async (event, { action, options }) => {
    if (os.platform() !== 'darwin') return { success: false, error: 'Recording only supported on macOS' };
-    
+
    // Path to bundled aperture binary
    // In dev: ./resources/bin/aperture
    // In prod: process.resourcesPath/bin/aperture
-    const binPath = app.isPackaged 
+    const binPath = app.isPackaged
      ? path.join(process.resourcesPath, 'bin', 'aperture')
      : path.join(__dirname, '../../resources/bin/aperture'); // Adjust based on structure

    if (action === 'start') {
      if (recordingProcess) return { success: false, error: 'Recording already in progress' };
-      
+
      const { fps = 30, audioDeviceId, output } = options || {};
      const cleanOutput = expandPath(output || '~/tmp/recording.mp4');
-      
+
      const args = ['run', '--fps', fps, '--output', cleanOutput];
      if (audioDeviceId) args.push('--audio-device-id', audioDeviceId);
-      
+
      // Spawn process
      // Note: aperture is a CLI tool. We might need 'aperture' node package or the binary.
      // Assuming binary usage here.
      try {
        console.log(`Starting recording: ${binPath} ${args.join(' ')}`);
        recordingProcess = spawn(binPath, args);
-        
+
        recordingProcess.on('error', (err: any) => {
            console.error('Recording error:', err);
            recordingProcess = null;
@@ -152,7 +307,7 @@ export function registerSystemHandlers() {

    } else if (action === 'stop') {
      if (!recordingProcess) return { success: false, error: 'No recording in progress' };
-      
+
      recordingProcess.kill('SIGINT'); // Send interrupt to stop cleanly
      recordingProcess = null;
      return { success: true };
@@ -163,35 +318,156 @@ export function registerSystemHandlers() {
    return { success: false, error: 'Unknown action' };
  });

-  // 6. Set Display Layout (Displayplacer)
+  // 6. Set Display Layout
+  // Primary path: display_control (native CoreGraphics, no external deps).
+  //   Build from scripts/display_control.m via scripts/build-display-control.sh on a Mac.
+  //   Commit the resulting resources/bin/display_control binary to the repo.
+  // Fallback: displayplacer (requires: brew install displayplacer on each venue Mac).
+  //   Also supports per-device configStr override (displayplacer format).
  ipcMain.handle('native:set-display-layout', async (event, { mode, configStr }) => {
    if (os.platform() !== 'darwin') return { success: false, error: 'Display control only supported on macOS' };
-    
-    const binPath = app.isPackaged 
-      ? path.join(process.resourcesPath, 'bin', 'displayplacer')
-      : path.join(__dirname, '../../resources/bin/displayplacer');

-    let cmd = '';
-    
+    // Primary: display_control — native CoreGraphics, no Homebrew dependency.
+    // Derived from OSIT MasterKey app (LegacyUtilities.m). No configStr support needed —
+    // CoreGraphics auto-detects all connected displays.
+    const dc_bin = app.isPackaged
+      ? path.join(process.resourcesPath, 'bin', 'display_control')
+      : path.join(__dirname, '../../resources/bin/display_control');
+
+    if (fs.existsSync(dc_bin) && !configStr) {
+      if (mode !== 'mirror' && mode !== 'extend') {
+        return { success: false, error: `Unsupported display mode: ${mode}` };
+      }
+      return await runExec(`"${dc_bin}" ${mode}`);
+    }
+
+    // Fallback: displayplacer — required when display_control binary is not built yet,
+    // or when a per-device configStr override is set (displayplacer-format string from event_device.data_json).
+    // Install: brew install displayplacer
+    const _dp_candidates = app.isPackaged
+      ? [path.join(process.resourcesPath, 'bin', 'displayplacer')]
+      : [
+          path.join(__dirname, '../../resources/bin/displayplacer'),
+          '/opt/homebrew/bin/displayplacer',   // Apple Silicon Homebrew
+          '/usr/local/bin/displayplacer',       // Intel Homebrew
+        ];
+    const dpPath = _dp_candidates.find(p => fs.existsSync(p)) ?? _dp_candidates[0];
+
+    // Explicit configStr takes priority — allows manual per-device override.
+    if (configStr) {
+      return await runExec(`"${dpPath}" ${configStr}`);
+    }
+
+    // Auto-detect via `displayplacer list`.
+    const list_result = await runExec(`"${dpPath}" list`);
+    if (!list_result.success || !list_result.stdout) {
+      return { success: false, error: `displayplacer not available. Build display_control from scripts/build-display-control.sh or run: brew install displayplacer` };
+    }
+
+    // The command line looks like: displayplacer "id:xxx res:... origin:(0,0) ..." "id:yyy ..."
+    const cmd_line = list_result.stdout.split('\n').find(l => l.trim().startsWith('displayplacer "'));
+    if (!cmd_line) {
+      return { success: false, error: 'Only one display connected or displayplacer list output unrecognised' };
+    }
+
+    const display_strings = [...cmd_line.matchAll(/"([^"]+)"/g)].map(m => m[1]);
+    if (display_strings.length < 2) {
+      return { success: false, error: 'Only one display found; cannot change layout' };
+    }
+
    if (mode === 'mirror') {
-        // This usually requires querying current IDs, which is complex.
-        // If configStr is provided (output of 'displayplacer list'), use it.
-        if (configStr) {
-            cmd = `"${binPath}" ${configStr}`;
-        } else {
-             return { success: false, error: 'Config string required for now' };
-        }
-    } else if (mode === 'extend') {
-        if (configStr) {
-            cmd = `"${binPath}" ${configStr}`;
-        }
+      const primary_id_match = display_strings[0].match(/\bid:([^\s]+)/);
+      if (!primary_id_match) {
+        return { success: false, error: 'Could not parse primary display ID from displayplacer output' };
+      }
+      const primary_id = primary_id_match[1];
+
+      const mirror_args = display_strings.map((s, i) => {
+        if (i === 0) return `"${s}"`;
+        const without_existing_mirror = s.replace(/\s*mirror_of_display:\S+/g, '').trim();
+        return `"${without_existing_mirror} mirror_of_display:${primary_id}"`;
+      }).join(' ');
+
+      return await runExec(`"${dpPath}" ${mirror_args}`);
    }

-    if (cmd) {
-        return await runExec(cmd);
+    if (mode === 'extend') {
+      const any_mirrored = display_strings.some(s => /\bmirror_of_display:\S+/.test(s));
+      if (!any_mirrored) {
+        return await runExec(`"${dpPath}" ${display_strings.map(s => `"${s}"`).join(' ')}`);
+      }
+
+      let x_offset = 0;
+      const extend_args = display_strings.map((s) => {
+        const without_mirror = s.replace(/\s*mirror_of_display:\S+/g, '').trim();
+        const res_match = without_mirror.match(/\bres:(\d+)x\d+/);
+        const width = res_match ? parseInt(res_match[1]) : 1920;
+        const updated = without_mirror.replace(/\borigin:\([^)]+\)/, `origin:(${x_offset},0)`);
+        x_offset += width;
+        return `"${updated}"`;
+      }).join(' ');
+
+      return await runExec(`"${dpPath}" ${extend_args}`);
    }
-    
-    return { success: false, error: 'Invalid mode or missing config' };
+
+    return { success: false, error: `Unsupported display mode: ${mode}` };
+  });
+
+  // 6b. List Display Modes
+  ipcMain.handle('native:list-display-modes', async () => {
+    if (os.platform() !== 'darwin') return { success: false, error: 'Display control only supported on macOS' };
+
+    const dc_bin = app.isPackaged
+      ? path.join(process.resourcesPath, 'bin', 'display_control')
+      : path.join(__dirname, '../../resources/bin/display_control');
+
+    if (!fs.existsSync(dc_bin)) {
+      return { success: false, error: 'display_control binary not found. Build via scripts/build-display-control.sh.' };
+    }
+
+    const result = await runExec(`"${dc_bin}" list-modes`);
+    if (!result.success || !result.stdout) {
+      return { success: false, error: result.error ?? 'list-modes returned no output' };
+    }
+
+    try {
+      const displays = JSON.parse(result.stdout);
+      return { success: true, displays };
+    } catch (e: any) {
+      return { success: false, error: `Failed to parse list-modes output: ${e.message}`, raw: result.stdout };
+    }
+  });
+
+  // 6c. Set Display Mode
+  ipcMain.handle('native:set-display-mode', async (event, {
+    display_index,
+    width,
+    height,
+    refresh_rate,
+    hidpi
+  }: {
+    display_index: number;
+    width: number;
+    height: number;
+    refresh_rate?: number;
+    hidpi?: boolean | null;
+  }) => {
+    if (os.platform() !== 'darwin') return { success: false, error: 'Display control only supported on macOS' };
+
+    const dc_bin = app.isPackaged
+      ? path.join(process.resourcesPath, 'bin', 'display_control')
+      : path.join(__dirname, '../../resources/bin/display_control');
+
+    if (!fs.existsSync(dc_bin)) {
+      return { success: false, error: 'display_control binary not found. Build via scripts/build-display-control.sh.' };
+    }
+
+    let cmd = `"${dc_bin}" set-mode ${display_index} ${width} ${height}`;
+    if (refresh_rate) cmd += ` --refresh ${refresh_rate}`;
+    if (hidpi === true)  cmd += ' --hidpi';
+    if (hidpi === false) cmd += ' --no-hidpi';
+
+    return await runExec(cmd);
  });

  // 7. Update App
@@ -210,10 +486,10 @@ export function registerSystemHandlers() {
                url: url,
                responseType: 'stream'
            });
-            
+
            const writer = fs.createWriteStream(destPath);
            response.data.pipe(writer);
-            
+
            await new Promise((resolve, reject) => {
                writer.on('finish', () => resolve(true));
                writer.on('error', reject);
@@ -237,9 +513,9 @@ export function registerSystemHandlers() {
    // Real implementation depends on OS and packaging format.
    // macOS: Mount DMG, copy .app to /Applications? Or Unzip .app?
    // Linux: chmod +x AppImage and move?
-    
+
    console.log(`Ready to install update from: ${updateFile}`);
-    
+
    // For now, just return success so the UI knows we "downloaded" it.
    return { success: true, message: 'Update downloaded/located. Installation logic requires packaging specifics.', downloadedPath: updateFile };
  });
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -5,7 +5,7 @@ contextBridge.exposeInMainWorld('aetherNative', {
  get_device_config: () => ipcRenderer.invoke('get-device-config'),
  get_jwt: () => ipcRenderer.invoke('get-jwt'),
  get_device_info: () => ipcRenderer.invoke('get-device-info'),
-  
+
  open_folder: (path: string) => ipcRenderer.invoke('native:open-folder', path),
  run_cmd: (args: any) => ipcRenderer.invoke('native:run-cmd', args),
  run_cmd_sync: (args: any) => ipcRenderer.invoke('native:run-cmd-sync', args),
@@ -27,6 +27,8 @@ contextBridge.exposeInMainWorld('aetherNative', {
  window_control: (args: any) => ipcRenderer.invoke('native:window-control', args),
  manage_recording: (args: any) => ipcRenderer.invoke('native:manage-recording', args),
  set_display_layout: (args: any) => ipcRenderer.invoke('native:set-display-layout', args),
+  list_display_modes: () => ipcRenderer.invoke('native:list-display-modes'),
+  set_display_mode: (args: any) => ipcRenderer.invoke('native:set-display-mode', args),
  power_control: (args: any) => ipcRenderer.invoke('native:power-control', args),
  open_external: (args: any) => ipcRenderer.invoke('native:open-external', args),
 });
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1,3 +1,26 @@
+export interface DisplayMode {
+  index: number;
+  width: number;
+  height: number;
+  refresh: number;
+  pixel_width: number;
+  pixel_height: number;
+  hidpi: boolean;
+  is_current: boolean;
+}
+
+export interface DisplayInfo {
+  index: number;
+  id: number;
+  is_main: boolean;
+  current_width: number;
+  current_height: number;
+  current_refresh: number;
+  current_pixel_width: number;
+  current_pixel_height: number;
+  modes: DisplayMode[];
+}
+
 export interface SeedConfig {
  event_device_id: string;
  primary_api_base_url: string;
@@ -37,6 +60,8 @@ export interface AetherNativeBridge {
  open_external: (args: {url: string, app?: 'chrome' | 'firefox'}) => Promise<{success: boolean, error?: string}>;
  manage_recording: (args: {action: 'start' | 'stop' | 'status', options?: {fps?: number, audioDeviceId?: string, output?: string}}) => Promise<{success: boolean, isRecording?: boolean, pid?: number, error?: string}>;
  set_display_layout: (args: {mode: 'mirror' | 'extend', configStr?: string | null}) => Promise<{success: boolean, error?: string, stdout?: string, stderr?: string}>;
+  list_display_modes: () => Promise<{success: boolean, displays?: DisplayInfo[], error?: string, raw?: string}>;
+  set_display_mode: (args: {display_index: number, width: number, height: number, refresh_rate?: number, hidpi?: boolean | null}) => Promise<{success: boolean, stdout?: string, stderr?: string, error?: string}>;
  update_app: (args: {source: 'url' | 'file', url?: string, path?: string}) => Promise<{success: boolean, message?: string, downloadedPath?: string, error?: string}>;

  // Self-Documentation
Author	SHA1	Message	Date
Scott Idem	99e0ebb7c3	docs: update TODO_AGENTS — current display_control status + future ideas section	2026-05-20 18:43:14 -04:00
Scott Idem	51db51d991	docs/build: update README + compiled dist for list-modes/set-mode features README: - set_display_layout: note idempotent behavior (no flicker if already in state) - add list_display_modes and set_display_mode rows to bridge table - add list-modes and set-mode to Option B test commands dist/: compiled output from tsc (system_handlers, preload, index)	2026-05-20 18:27:58 -04:00
Scott Idem	6cddd69891	fix(display): skip mirror/extend if already in requested state mirror_displays() now checks CGDisplayMirrorsDisplay() for each secondary before calling CGBeginDisplayConfiguration — avoids a needless display reconfiguration (and potential flicker) when already mirrored. extend_displays() already had this check; no change needed there.	2026-05-20 18:24:33 -04:00
Scott Idem	58060aea8a	build: rebuild display_control binary (list-modes + set-mode)	2026-05-20 18:17:17 -04:00
Scott Idem	54308c6d4a	feat(display): add list-modes and set-mode commands display_control.m: list-modes — JSON array of all online displays with every usable mode (width, height, refresh, pixel_width, pixel_height, hidpi, is_current) set-mode <display_index> <width> <height> [--refresh <hz>] [--hidpi] [--no-hidpi] — picks best matching CGDisplayMode; auto-prefers HiDPI on built-in and non-HiDPI on externals; highest refresh wins on ties system_handlers.ts: native:list-display-modes — runs binary, parses JSON, returns displays[] native:set-display-mode — runs binary with supplied args preload/index.ts + shared/types.ts: list_display_modes() / set_display_mode() exposed through bridge with full types	2026-05-20 18:16:43 -04:00
Scott Idem	b2cd0736df	fix: use window.maximize() instead of explicit workArea dimensions Electron screen.workArea is unreliable on KDE — returns full bounds, causing the window to extend behind the taskbar. Delegating to the native WM via mainWindow.maximize() works correctly on KDE, macOS, and Linux.	2026-05-20 18:14:26 -04:00
Scott Idem	a230ff09de	fix: use workArea instead of bounds for initial window size Respects taskbar on Linux (KDE etc.) and menu bar on macOS. bounds caused the window to extend behind the taskbar on KDE. workArea gives {x, y, width, height} of the usable screen region.	2026-05-20 17:54:05 -04:00
Scott Idem	7199d45719	feat: single instance lock; auto-size window to primary display bounds - requestSingleInstanceLock(): second launch focuses existing window and quits. - Window width/height/x/y set from screen.getPrimaryDisplay().bounds so the app fills the built-in display exactly on launch, regardless of resolution.	2026-05-20 17:48:09 -04:00
Scott Idem	48e24af84e	build: recompile dist after display_control fail-fast fix	2026-05-20 17:45:01 -04:00
Scott Idem	cd1cd02bc2	build: commit display_control universal binary; fix packaging to extract to Resources/bin - resources/bin/display_control: universal Mach-O (x86_64 + arm64), built via scripts/remote-build-display-control.sh on laptop 01. - package:mac: add --extra-resource=resources/bin so the binary lands at [AppName].app/Contents/Resources/bin/ (outside app.asar) and is executable at runtime via process.resourcesPath.	2026-05-20 17:32:08 -04:00
Scott Idem	0ae0d644a9	build: add display_control binary (universal x86_64+arm64)	2026-05-20 17:28:39 -04:00
Scott Idem	ce2832a584	fix(build): replace scp with ssh+cat to handle space in username scp's own user@host:path parser splits on the space in 'speaker ready' even when the shell argument is quoted. ssh already handles it correctly. Upload: ssh cat < file; Download: ssh cat > file.	2026-05-20 17:22:34 -04:00
Scott Idem	b6b902ad4a	feat(build): add remote-build-display-control.sh for workstation → Mac builds Copies display_control.m to laptop 01 via SSH, compiles universal binary (x86_64 + arm64) on the remote Mac, pulls binary back to resources/bin/. Defaults to 192.168.32.101; accepts optional IP override as $1. README: restructure display_control build section — Option A (remote from workstation, preferred) and Option B (direct on Mac).	2026-05-20 17:16:25 -04:00
Scott Idem	3da3b187ec	build(display): universal binary — compile x86_64 + arm64 and lipo into fat binary Compiles both arches separately then links with lipo -create. Prevents silent failure when a binary built on Apple Silicon is deployed to Intel venue Macs (MacBook Air 2018 fleet).	2026-05-20 17:10:56 -04:00
Scott Idem	86ea73bfbd	fix(display): fail fast on invalid mode in display_control path; update docs - Primary display_control path now validates mode explicitly ('mirror'\|'extend') and returns an error instead of silently defaulting to extend. Passes mode directly to binary (simpler, avoids redundant ternary). - README: update set_display_layout bridge table row to correctly describe display_control as primary and displayplacer as fallback. - README: add one-time 'Build display_control Binary' section in Development with xcode-select, build, test, and git commit steps.	2026-05-20 17:04:39 -04:00
Scott Idem	a14c7c7a3f	feat(display): add display_control CoreGraphics binary, replace displayplacer as primary path Derived from OSIT MasterKey app (LegacyUtilities.m, Ian Kohl 2019). Uses CGConfigureDisplayMirrorOfDisplay — native macOS API, no Homebrew dependency. Handler now tries display_control first; falls back to displayplacer for missing binary or per-device configStr overrides. Build the binary via scripts/build-display-control.sh on a Mac (requires Xcode CLT only), then commit resources/bin/display_control. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-20 16:48:19 -04:00
Scott Idem	9df9d884e5	fix(display): fix mirror_of_display syntax, add Homebrew fallback, update docs - `mirror:` was wrong; correct displayplacer param is `mirror_of_display:<uuid>` - Same fix applied to the strip regex (extend path) and mirror detection check - Binary lookup now tries resources/bin → /opt/homebrew/bin → /usr/local/bin so dev/venue Macs with `brew install displayplacer` work without bundling - Updated TODO_AGENTS.md: marks auto-detection complete, documents one-time brew install step, bundling path, and optional per-device configStr override Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-20 16:33:25 -04:00
Scott Idem	2bf4d7c141	New build for Mac	2026-05-20 15:52:35 -04:00
Scott Idem	e37fd1ddbb	docs: sync README and list_tools() to current handler reality README: correct set_display_layout (auto-detection default, configStr optional); update set_wallpaper signature ({path?,url?,url_external?,display?,api_key?, account_id?}); remove stale note on launch_presentation -e flag (hardened 2026-05-11). list_tools(): expand from 13 entries to 22 — adds copy_from_cache_to_temp, set_wallpaper, set_display_layout, window_control, power_control, manage_recording, update_app, open_external, get_device_config; updates launch_from_cache params (adds native_template); adds category comments; improves all descriptions to reflect current behavior. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-20 15:39:27 -04:00
Scott Idem	a1e74829e8	fix(display): auto-detect displays for mirror/extend via displayplacer list The handler was a stub that required an explicit configStr — the Svelte caller never provides one, so mirror/extend silently failed every launch. Now auto-detects connected displays: - mirror: parses displayplacer list output, adds mirror:<primary_id> to secondary display(s); removes any existing mirror key first. - extend: re-applies current layout if already extended; otherwise strips mirror keys and computes side-by-side origins from each display's width. - configStr still takes priority when provided (manual per-device override). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-05-20 15:23:01 -04:00
Scott Idem	2c7b609295	Updated dist files	2026-05-13 19:09:09 -04:00
Scott Idem	1008a55ec3	Adjust Linux wallpaper test mode	2026-05-13 18:57:27 -04:00
Scott Idem	c8fdb8b1e7	Harden wallpaper downloads	2026-05-13 18:43:58 -04:00
Scott Idem	bb51771dc7	Expand wallpaper handling	2026-05-13 18:08:49 -04:00
Scott Idem	53d200f10e	Version bump because things are in a good state.	2026-05-13 17:31:16 -04:00