Add npm packaging and service support

Author: DjDeveloperr

.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  ci:
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: |
+            package-lock.json
+            client/package-lock.json
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Install root dependencies
+        run: npm ci
+
+      - name: Install client dependencies
+        run: npm ci --prefix client
+
+      - name: Lint, build, and test
+        run: npm run ci

.prettierignore

@@ -0,0 +1,7 @@
+.claude
+.git
+.vscode
+build
+client/dist
+node_modules
+server/target

README.md

@@ -19,10 +19,26 @@
 ./scripts/build-cli.sh
 ```
 
+## Install
+
+Install the published CLI globally:
+
+```sh
+npm install -g xcode-canvas-web
+```
+
+Install the current local checkout globally from source:
+
+```sh
+npm install -g .
+```
+
+After a global install, use the `xcode-canvas-web` command directly. From a local checkout, you can also run `./build/xcode-canvas-web`.
+
 ## Run
 
 ```sh
-./build/xcode-canvas-web serve --port 4310
+xcode-canvas-web serve --port 4310
 ```
 
 Then open [http://127.0.0.1:4310](http://127.0.0.1:4310).
@@ -31,44 +47,32 @@ The Rust server exposes HTTP on the requested port and WebTransport on `port + 1
 The browser bootstrap comes from `GET /api/health`, which returns the WebTransport URL template,
 certificate hash, and packet version needed by the client.
 
-To expose the server on your LAN, bind on all interfaces and advertise a host
-or IP that the browser can actually reach and validate in the self-signed
-certificate:
+## Service
+
+Enable the per-user background service with `launchd`:
 
 ```sh
-./build/xcode-canvas-web serve --port 4310 --bind 0.0.0.0 --advertise-host 192.168.1.50
+xcode-canvas-web service on --port 4310
 ```
 
-Then open `http://192.168.1.50:4310` from another device on the same network.
+Disable it:
+
+```sh
+xcode-canvas-web service off
+```
 
 ## CLI
 
 ```sh
-./build/xcode-canvas-web list
-./build/xcode-canvas-web boot <udid>
-./build/xcode-canvas-web shutdown <udid>
-./build/xcode-canvas-web open-url <udid> https://example.com
-./build/xcode-canvas-web launch <udid> com.apple.Preferences
+xcode-canvas-web list
+xcode-canvas-web boot <udid>
+xcode-canvas-web shutdown <udid>
+xcode-canvas-web open-url <udid> https://example.com
+xcode-canvas-web launch <udid> com.apple.Preferences
 ```
 
-## HTTP API
-
-- `GET /api/health`
-- `GET /api/metrics`
-- `GET /api/simulators`
-- `POST /api/simulators/:udid/boot`
-- `POST /api/simulators/:udid/shutdown`
-- `POST /api/simulators/:udid/open-url`
-- `POST /api/simulators/:udid/launch`
-- `POST /api/simulators/:udid/touch`
-- `POST /api/simulators/:udid/key`
-- `POST /api/simulators/:udid/home`
-- `POST /api/simulators/:udid/rotate-right`
-- `GET /api/simulators/:udid/chrome-profile`
-- `GET /api/simulators/:udid/chrome.png`
-
-## Status
-
-The live browser preview now comes from the vendored private display bridge rather than `simctl io screenshot`.
-The Rust server owns REST routing, session orchestration, metrics, static file serving, and the WebTransport video path.
-The native layer owns simulator lookup/boot, chrome rendering, HID input injection, and hardware H.264 encode.
+## License
+
+Copyright 2026 Dj
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).

bin/xcode-canvas-web.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+const binaryPath = path.join(packageRoot, "build", "xcode-canvas-web-bin");
+
+if (!existsSync(binaryPath)) {
+  console.error(
+    "xcode-canvas-web is not built yet. Reinstall or rebuild the package so the native CLI is available.",
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  cwd: process.cwd(),
+  stdio: "inherit",
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

cli/DFPrivateSimulatorDisplayBridge.m

@@ -415,14 +415,16 @@ static void DFTrieDescend(DFTrieContext *ctx, const uint8_t *node, size_t nameLe
 }
 
 static id DFDigitizerDelegateGetter(id self, SEL _cmd) {
+    (void)_cmd;
     return objc_getAssociatedObject(self, DFDigitizerDelegateAssociationKey);
 }
 
 static id DFDigitizerWakeDelegateGetter(id self, SEL _cmd) {
+    (void)_cmd;
     return objc_getAssociatedObject(self, DFDigitizerWakeDelegateAssociationKey);
 }
 
-static Class DFEnsureDigitizerProxyClass(Class baseClass) {
+static Class __attribute__((unused)) DFEnsureDigitizerProxyClass(Class baseClass) {
     if (baseClass == Nil) {
         return Nil;
     }
@@ -505,7 +507,7 @@ __asm__ volatile(
     return result;
 }
 
-static id DFCallSwiftSelfGetter(id selfObject, const char *symbolName) {
+static id __attribute__((unused)) DFCallSwiftSelfGetter(id selfObject, const char *symbolName) {
     if (selfObject == nil) return nil;
     void *function = dlsym(RTLD_DEFAULT, symbolName);
     if (function == NULL) {
@@ -541,6 +543,7 @@ static id DFCallSwiftSelfGetterByPattern(id selfObject, const char *prefix, cons
     NSMutableDictionary<NSNumber *, id> *unwrapped = [NSMutableDictionary dictionaryWithCapacity:[(NSDictionary *)screens count]];
     SEL screenSelector = sel_registerName("screen");
     [(NSDictionary *)screens enumerateKeysAndObjectsUsingBlock:^(id key, id value, BOOL *stop) {
+        (void)stop;
         if (![key isKindOfClass:[NSNumber class]] || value == nil) {
             return;
         }
@@ -556,7 +559,7 @@ static id DFCallSwiftSelfGetterByPattern(id selfObject, const char *prefix, cons
     return unwrapped;
 }
 
-static uint32_t DFCallSwiftSelfGetterU32(id selfObject, const char *symbolName) {
+static uint32_t __attribute__((unused)) DFCallSwiftSelfGetterU32(id selfObject, const char *symbolName) {
     if (selfObject == nil) {
         return 0;
     }
@@ -578,7 +581,7 @@ __asm__ volatile(
     return result;
 }
 
-static uintptr_t DFCallSwiftUWordGetter(const char *symbolName) {
+static uintptr_t __attribute__((unused)) DFCallSwiftUWordGetter(const char *symbolName) {
     if (symbolName == NULL) {
         return 0;
     }
@@ -599,7 +602,7 @@ __asm__ volatile(
     return result;
 }
 
-static BOOL DFCallSwiftVoidMethodWithSelfAndTwoArgs(id selfObject, id firstArgument, const void *secondArgument, const char *symbolName) {
+static BOOL __attribute__((unused)) DFCallSwiftVoidMethodWithSelfAndTwoArgs(id selfObject, id firstArgument, const void *secondArgument, const char *symbolName) {
     if (selfObject == nil || firstArgument == nil || secondArgument == nil) {
         return NO;
     }
@@ -637,7 +640,7 @@ __asm__ volatile(
     return YES;
 }
 
-static BOOL DFCallSwiftVoidMethodWithSelfAndObject(id selfObject, id firstArgument, const char *symbolName) {
+static BOOL __attribute__((unused)) DFCallSwiftVoidMethodWithSelfAndObject(id selfObject, id firstArgument, const char *symbolName) {
     if (selfObject == nil || firstArgument == nil) return NO;
     void *function = dlsym(RTLD_DEFAULT, symbolName);
     if (function == NULL) {
@@ -653,7 +656,7 @@ static BOOL DFCallSwiftVoidMethodWithSelfAndObjectByPattern(id selfObject, id fi
     return DFCallSwiftVoidMethodWithSelfAndObjectByFunction(selfObject, firstArgument, function);
 }
 
-static BOOL DFCallSwiftVoidMethodWithSelfAndUWordAndBool(id selfObject, uintptr_t firstArgument, BOOL secondArgument, const char *symbolName) {
+static BOOL __attribute__((unused)) DFCallSwiftVoidMethodWithSelfAndUWordAndBool(id selfObject, uintptr_t firstArgument, BOOL secondArgument, const char *symbolName) {
     if (selfObject == nil) {
         return NO;
     }
@@ -676,7 +679,7 @@ __asm__ volatile(
     return YES;
 }
 
-static BOOL DFCallSwiftThrowingMethodWithSelfAndObjectAndUWord(id selfObject, id firstArgument, uintptr_t secondArgument, const char *symbolName, NSError **error) {
+static BOOL __attribute__((unused)) DFCallSwiftThrowingMethodWithSelfAndObjectAndUWord(id selfObject, id firstArgument, uintptr_t secondArgument, const char *symbolName, NSError **error) {
     if (selfObject == nil || firstArgument == nil) {
         return NO;
     }
@@ -1055,7 +1058,7 @@ __asm__ volatile(
     return YES;
 }
 
-static BOOL DFCallSwiftUnitAngleMeasurementGetter(id selfObject, const char *symbolName, DFUnitAngleMeasurement *measurement) {
+static BOOL __attribute__((unused)) DFCallSwiftUnitAngleMeasurementGetter(id selfObject, const char *symbolName, DFUnitAngleMeasurement *measurement) {
     if (selfObject == nil || measurement == NULL) return NO;
     void *function = dlsym(RTLD_DEFAULT, symbolName);
     if (function == NULL) {
@@ -1089,7 +1092,7 @@ __asm__ volatile(
     return YES;
 }
 
-static BOOL DFCallSwiftUnitAngleMeasurementSetter(id selfObject, DFUnitAngleMeasurement measurement, const char *symbolName) {
+static BOOL __attribute__((unused)) DFCallSwiftUnitAngleMeasurementSetter(id selfObject, DFUnitAngleMeasurement measurement, const char *symbolName) {
     if (selfObject == nil) return NO;
     void *function = dlsym(RTLD_DEFAULT, symbolName);
     if (function == NULL) {
@@ -2132,13 +2135,15 @@ - (nullable instancetype)initWithUDID:(NSString *)udid error:(NSError * _Nullabl
         _screenAdapterCallbackUUID,
         _callbackQueue,
         ^(id simScreen) {
+            (void)simScreen;
             __strong typeof(weakSelf) strongSelf = weakSelf;
             if (strongSelf == nil) {
                 return;
             }
             [strongSelf updateStatus:@"CoreSimulator screen proxy connected"];
         },
         ^(id simScreen) {
+            (void)simScreen;
             __strong typeof(weakSelf) strongSelf = weakSelf;
             if (strongSelf == nil) {
                 return;
@@ -2248,6 +2253,7 @@ - (nullable instancetype)initWithUDID:(NSString *)udid error:(NSError * _Nullabl
             [strongSelf notifyDelegateOfFrame:strongSelf->_latestPixelBuffer];
         },
         ^(id surface, id maskedSurface) {
+            (void)maskedSurface;
             __strong typeof(weakSelf) strongSelf = weakSelf;
             if (strongSelf == nil) {
                 return;

client/index.html

@@ -2,7 +2,10 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, user-scalable=no"
+    />
     <meta name="color-scheme" content="light dark" />
     <title>Xcode Canvas Web</title>
   </head>

client/package.json

@@ -6,7 +6,8 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "tsc --noEmit && vite build",
+    "typecheck": "tsc --noEmit",
+    "build": "npm run typecheck && vite build",
     "preview": "vite preview",
     "test": "vitest run"
   },

client/src/api/client.ts

@@ -1,9 +1,12 @@
 import { API_ROOT } from "../shared/constants";
 
-export async function apiRequest<T>(path: string, options: RequestInit = {}): Promise<T> {
+export async function apiRequest<T>(
+  path: string,
+  options: RequestInit = {},
+): Promise<T> {
   const response = await fetch(`${API_ROOT}${path}`, {
     headers: { "Content-Type": "application/json" },
-    ...options
+    ...options,
   });
 
   const contentType = response.headers.get("content-type") ?? "";

client/src/api/controls.ts

@@ -5,20 +5,20 @@ import type {
   OpenUrlPayload,
   SimulatorMetadata,
   SimulatorResponse,
-  TouchPayload
+  TouchPayload,
 } from "./types";
 
 async function postSimulatorAction(
   udid: string,
   action: string,
-  payload?: KeyPayload | LaunchPayload | OpenUrlPayload | TouchPayload
+  payload?: KeyPayload | LaunchPayload | OpenUrlPayload | TouchPayload,
 ): Promise<SimulatorMetadata | null> {
   const response = await apiRequest<SimulatorResponse | { ok: boolean }>(
     `/api/simulators/${udid}/${action}`,
     {
       method: "POST",
-      body: payload ? JSON.stringify(payload) : undefined
-    }
+      body: payload ? JSON.stringify(payload) : undefined,
+    },
   );
 
   return "simulator" in response ? response.simulator : null;

client/src/api/simulators.ts

@@ -1,5 +1,9 @@
 import { apiRequest } from "./client";
-import type { ChromeProfile, SimulatorMetadata, SimulatorsResponse } from "./types";
+import type {
+  ChromeProfile,
+  SimulatorMetadata,
+  SimulatorsResponse,
+} from "./types";
 
 export async function listSimulators(): Promise<SimulatorMetadata[]> {
   const data = await apiRequest<SimulatorsResponse>("/api/simulators");