@telepath-computer/television-desktop 0.1.206 → 0.1.208

package/README.md

@@ -1,27 +1,33 @@
 # @telepath-computer/television-desktop
 
-Electron desktop wrapper for [Television](https://www.npmjs.com/package/@telepath-computer/television).
+The Television desktop application is an Electron client for a running [Television](https://www.npmjs.com/package/@telepath-computer/television) server. It renders URL artifacts as full embedded pages in addition to providing a native application window.
 
-## Install
+## Requirements
+
+The package requires Node.js `>=22.12.0`. Its baseline platforms are Linux, macOS, and Windows. On macOS, Television supports Apple Silicon running macOS 12 or later.
+
+## Install and run
 
 ```sh
-npm i -g @telepath-computer/television-desktop
+npm i -g @telepath-computer/television-desktop@latest
+tv-desktop
 ```
 
-## Run
+The connect window asks for the Television server URL and, when the server uses authentication, its token.
+
+The first launch after every install or upgrade prepares Electron's platform runtime and prints a message before it begins. A network download may be required. On macOS, this launch also prepares the Television application bundle so the Dock and application menu use the Television name and icon. Later launches from the same installation reuse the prepared runtime.
+
+Electron keeps downloaded macOS archives by version under `~/Library/Caches/electron`. Television does not prune this cache. It is safe to delete while Television is stopped; the next setup downloads the archive again.
+
+## Recovery
+
+If the launcher reports an incomplete or mismatched runtime, reinstall the package and launch again:
 
 ```sh
+npm i -g @telepath-computer/television-desktop@latest
 tv-desktop
 ```
 
-A connect window opens; point it at a running Television server. Enter the
-server URL plus token when the server runs with `--auth`; leave the token blank
-for no-auth servers.
-
-## macOS notes
+The reinstall replaces package-owned runtime files without deleting saved Television connections or other user data. A download failure instead means the network problem should be corrected before retrying `tv-desktop`.
 
-The first launch renames the bundled `Electron.app` to `Television.app`
-(bundle directory + inner executable + `Info.plist` + bundle icon). This
-is what gives the Dock and menu bar "Television" instead of "Electron".
-First launch is a few seconds slower; every launch after takes the fast
-path.
+The authoritative product behavior is [the desktop application spec](https://github.com/telepath-computer/television/blob/main/specs/product/desktop-app.md); runtime, launcher, branding, and test-harness contracts are mapped by [the desktop architecture spec](https://github.com/telepath-computer/television/blob/main/specs/arch/desktop/index.md).

package/bin/tv-desktop.cjs

@@ -1,40 +1,48 @@
 #!/usr/bin/env node
+
 const { spawn, spawnSync } = require("node:child_process");
+const { createRequire } = require("node:module");
 const path = require("node:path");
-const fs = require("node:fs");
+const { runDesktopLauncher } = require("../scripts/launcher-core.cjs");
 
-const appDir = path.join(__dirname, "..");
+const desktopPackageDirectory = path.join(__dirname, "..");
+const requireFromDesktop = createRequire(path.join(desktopPackageDirectory, "package.json"));
 
-function resolveExecutable() {
-  const electronPkgDir = path.dirname(require.resolve("electron/package.json"));
-  const distDir = path.join(electronPkgDir, "dist");
-  if (process.platform === "darwin") {
-    const renamed = path.join(distDir, "Television.app", "Contents", "MacOS", "Television");
-    if (fs.existsSync(renamed)) return renamed;
-    // npm runs our package's postinstall before electron's postinstall has
-    // downloaded the Electron.app, so we can't rely on a postinstall hook.
-    // Rename lazily on first launch (idempotent); subsequent launches take
-    // the fast path above.
-    const upstream = path.join(distDir, "Electron.app");
-    if (fs.existsSync(upstream)) {
-      spawnSync(process.execPath, [path.join(appDir, "scripts", "rename-bundle.cjs")], {
-        stdio: "inherit",
-      });
-      if (fs.existsSync(renamed)) return renamed;
-    }
+runDesktopLauncher(process.argv.slice(2), process.env, {
+  platform: process.platform,
+  desktopPackageDirectory,
+  resolveElectronPackageRoot() {
+    return path.dirname(requireFromDesktop.resolve("electron/package.json"));
+  },
+  readMacPlistValue(infoPlistPath, key) {
+    const result = spawnSync("plutil", ["-extract", key, "raw", "-o", "-", infoPlistPath], {
+      encoding: "utf8",
+    });
+    if (result.error) throw result.error;
+    if (result.status !== 0) throw new Error(`plutil exited with status ${result.status}`);
+    return result.stdout.replace(/\r?\n$/, "");
+  },
+  loadElectronResolver() {
+    return requireFromDesktop("electron");
+  },
+  runBranding() {
+    return spawnSync(process.execPath, [path.join(desktopPackageDirectory, "scripts", "rename-bundle.cjs")], {
+      stdio: "inherit",
+    }).status;
+  },
+  spawnElectron(executablePath, args, options) {
+    return spawn(executablePath, args, options);
+  },
+  writeStdout(line) {
+    process.stdout.write(`${line}\n`);
+  },
+  writeStderr(line) {
+    process.stderr.write(`${line}\n`);
+  },
+}).then((outcome) => {
+  if (outcome.kind === "signal") {
+    process.kill(process.pid, outcome.signal);
+  } else {
+    process.exitCode = outcome.code;
   }
-  return require("electron");
-}
-
-const env = { ...process.env };
-delete env.ELECTRON_RUN_AS_NODE;
-
-const child = spawn(resolveExecutable(), [appDir, ...process.argv.slice(2)], {
-  stdio: "inherit",
-  env,
-});
-
-child.on("exit", (code, signal) => {
-  if (signal) process.kill(process.pid, signal);
-  else process.exit(code ?? 0);
 });

package/dist/connect-page.cjs

@@ -8,15 +8,6 @@
     return ipcMatch?.[1]?.trim() || message;
   }
 
-  // ../layout/src/constants.ts
-  var LAYOUT_FULL_WIDTH_UNITS = 4;
-  var LAYOUT_FULL_HEIGHT_UNITS = 6;
-  var DEFAULT_LAYOUT_UNIT = 128;
-  var CARD_GAP = 16;
-  var CARD_WIDTH = DEFAULT_LAYOUT_UNIT * LAYOUT_FULL_WIDTH_UNITS + CARD_GAP * (LAYOUT_FULL_WIDTH_UNITS - 1);
-  var CARD_HEIGHT = DEFAULT_LAYOUT_UNIT * LAYOUT_FULL_HEIGHT_UNITS + CARD_GAP * (LAYOUT_FULL_HEIGHT_UNITS - 1);
-  var LAYOUT_MOBILE_BREAKPOINT_PX = CARD_WIDTH + CARD_GAP * 2;
-
   // ../../node_modules/@rupertsworld/event-target/dist/index.js
   var RESERVED_EVENT_KEYS = /* @__PURE__ */ new Set([
     "target",
@@ -81,10 +72,11 @@
   var ArtifactUpdatedEvent = defineEvent();
   var ArtifactRemovedEvent = defineEvent();
   var ArtifactContentChangedEvent = defineEvent();
-  var ScreenCreatedEvent = defineEvent();
-  var ScreenUpdatedEvent = defineEvent();
-  var ScreenRemovedEvent = defineEvent();
-  var ScreenChangedEvent = defineEvent();
+  var ChannelCreatedEvent = defineEvent();
+  var ChannelUpdatedEvent = defineEvent();
+  var ChannelRemovedEvent = defineEvent();
+  var ChannelChangedEvent = defineEvent();
+  var PinnedChannelsChangedEvent = defineEvent();
   var ArtifactFocusEvent = defineEvent();
   var ThemeChangedEvent = defineEvent();
 

package/dist/connect-preload.cjs

@@ -6,7 +6,20 @@ var import_electron = require("electron");
 // src/connect-screen.ts
 var GET_CONNECT_SCREEN_INTENT_CHANNEL = "television:get-connect-screen-intent";
 
+// src/native-navigation-key.ts
+var NATIVE_NAVIGATION_KEY_CHANNEL = "television:navigation-key";
+function isNativeNavigationKey(value) {
+  return value === "ArrowLeft" || value === "ArrowRight" || value === "ArrowUp" || value === "ArrowDown";
+}
+
 // src/connect-preload.ts
+import_electron.contextBridge.exposeInMainWorld("__televisionNativeBridge", {
+  onNavigationKey(callback) {
+    import_electron.ipcRenderer.on(NATIVE_NAVIGATION_KEY_CHANNEL, (_event, key) => {
+      if (isNativeNavigationKey(key)) callback(key);
+    });
+  }
+});
 if (window.location.protocol === "file:") {
   import_electron.contextBridge.exposeInMainWorld("television", {
     getConnectScreenIntent: () => import_electron.ipcRenderer.invoke(GET_CONNECT_SCREEN_INTENT_CHANNEL),

package/dist/electron.cjs

@@ -36,15 +36,6 @@ module.exports = __toCommonJS(index_exports);
 var import_electron2 = require("electron");
 var import_node_path2 = __toESM(require("node:path"), 1);
 
-// ../layout/src/constants.ts
-var LAYOUT_FULL_WIDTH_UNITS = 4;
-var LAYOUT_FULL_HEIGHT_UNITS = 6;
-var DEFAULT_LAYOUT_UNIT = 128;
-var CARD_GAP = 16;
-var CARD_WIDTH = DEFAULT_LAYOUT_UNIT * LAYOUT_FULL_WIDTH_UNITS + CARD_GAP * (LAYOUT_FULL_WIDTH_UNITS - 1);
-var CARD_HEIGHT = DEFAULT_LAYOUT_UNIT * LAYOUT_FULL_HEIGHT_UNITS + CARD_GAP * (LAYOUT_FULL_HEIGHT_UNITS - 1);
-var LAYOUT_MOBILE_BREAKPOINT_PX = CARD_WIDTH + CARD_GAP * 2;
-
 // ../../node_modules/@rupertsworld/event-target/dist/index.js
 var RESERVED_EVENT_KEYS = /* @__PURE__ */ new Set([
   "target",
@@ -109,10 +100,11 @@ var ArtifactCreatedEvent = defineEvent();
 var ArtifactUpdatedEvent = defineEvent();
 var ArtifactRemovedEvent = defineEvent();
 var ArtifactContentChangedEvent = defineEvent();
-var ScreenCreatedEvent = defineEvent();
-var ScreenUpdatedEvent = defineEvent();
-var ScreenRemovedEvent = defineEvent();
-var ScreenChangedEvent = defineEvent();
+var ChannelCreatedEvent = defineEvent();
+var ChannelUpdatedEvent = defineEvent();
+var ChannelRemovedEvent = defineEvent();
+var ChannelChangedEvent = defineEvent();
+var PinnedChannelsChangedEvent = defineEvent();
 var ArtifactFocusEvent = defineEvent();
 var ThemeChangedEvent = defineEvent();
 
@@ -182,6 +174,7 @@ function buildRemoteURL(serverURL, token, desktopAppVersion) {
 }
 
 // src/connect-preflight.ts
+var HTTP_OK = 200;
 var HTTP_UNAUTHORIZED = 401;
 var DEFAULT_PREFLIGHT_TIMEOUT_MS = 8e3;
 var NOT_TV_SERVER_MESSAGE = "This URL doesn't seem to be a Television server \u2014 please check it.";
@@ -195,19 +188,19 @@ function unreachable(serverURL) {
 function notTVServer() {
   return { ok: false, code: "not-tv-server", message: NOT_TV_SERVER_MESSAGE };
 }
-function isDisplayResponse(body) {
-  if (typeof body !== "object" || body === null) return false;
-  const candidate = body;
-  return (typeof candidate.activeScreenID === "string" || candidate.activeScreenID === null) && (typeof candidate.activeThemeName === "string" || candidate.activeThemeName === null) && typeof candidate.acpEnabled === "boolean";
+function isDesktopConnectCheckResponse(body) {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) return false;
+  return body.product === "television";
 }
 async function preflightConnection(options) {
   const fetchImpl = options.fetchImpl ?? fetch;
-  const probeURL = new URL(options.probePath ?? "/display", options.serverURL).toString();
+  const probeURL = new URL("/desktop/connect-check", options.serverURL);
+  probeURL.searchParams.set("desktopAppVersion", options.desktopAppVersion);
   const headers = {};
   if (options.token) headers.Authorization = `Bearer ${options.token}`;
   let response;
   try {
-    response = await fetchImpl(probeURL, {
+    response = await fetchImpl(probeURL.toString(), {
       method: "GET",
       headers,
       signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS)
@@ -221,7 +214,7 @@ async function preflightConnection(options) {
     }
     return { ok: false, code: "auth-rejected", message: "Token rejected" };
   }
-  if (!response.ok) {
+  if (response.status !== HTTP_OK) {
     return notTVServer();
   }
   let body;
@@ -230,7 +223,7 @@ async function preflightConnection(options) {
   } catch {
     return notTVServer();
   }
-  if (!isDisplayResponse(body)) {
+  if (!isDesktopConnectCheckResponse(body)) {
     return notTVServer();
   }
   return { ok: true };
@@ -264,6 +257,26 @@ function saveConnection(connection) {
 // src/connect-screen.ts
 var GET_CONNECT_SCREEN_INTENT_CHANNEL = "television:get-connect-screen-intent";
 
+// src/native-navigation-key.ts
+var NATIVE_NAVIGATION_KEY_CHANNEL = "television:navigation-key";
+function isNativeNavigationKey(value) {
+  return value === "ArrowLeft" || value === "ArrowRight" || value === "ArrowUp" || value === "ArrowDown";
+}
+function handleNativeNavigationKey(event, input, platform, deliver) {
+  if (input.type !== "keyDown" || input.isComposing || !isNativeNavigationKey(input.key)) {
+    return false;
+  }
+  const matchesPlatformChord = platform === "darwin" ? input.alt && !input.control && !input.meta && !input.shift : input.control && !input.alt && !input.meta && !input.shift;
+  if (!matchesPlatformChord) return false;
+  event.preventDefault();
+  deliver(input.key);
+  return true;
+}
+
+// src/window-measures.ts
+var WINDOW_MIN_WIDTH_PX = 500;
+var WINDOW_MIN_HEIGHT_PX = 500;
+
 // src/index.ts
 import_electron2.app.setName("Television");
 var WINDOW_WIDTH = 1400;
@@ -320,6 +333,8 @@ var App = class {
       icon: import_node_path2.default.join(__dirname, "..", "assets", "icon.png"),
       width: WINDOW_WIDTH,
       height: WINDOW_HEIGHT,
+      minWidth: WINDOW_MIN_WIDTH_PX,
+      minHeight: WINDOW_MIN_HEIGHT_PX,
       show: false,
       backgroundColor: "#000000",
       titleBarStyle: "hidden",
@@ -367,29 +382,39 @@ var App = class {
       return { ok: false, message };
     }
     try {
+      const desktopAppVersion = resolveDesktopAppVersion(import_electron2.app.getVersion(), process.env);
       const preflight = await preflightConnection({
         serverURL: connection.serverURL,
-        token: connection.token
+        token: connection.token,
+        desktopAppVersion
       });
       if (!preflight.ok) {
         return { ok: false, message: preflight.message };
       }
       saveConnection(connection);
-      await this.loadRemote(connection);
+      await this.loadRemote(connection, desktopAppVersion);
       return { ok: true };
     } catch (error) {
       const message = error instanceof Error ? error.message : "Failed to connect";
       return { ok: false, message };
     }
   }
-  async loadRemote(connection) {
+  async loadRemote(connection, desktopAppVersion) {
     if (!this.window) return;
-    await this.window.loadURL(
-      buildRemoteURL(connection.serverURL, connection.token, resolveDesktopAppVersion(import_electron2.app.getVersion(), process.env))
-    );
+    await this.window.loadURL(buildRemoteURL(connection.serverURL, connection.token, desktopAppVersion));
   }
   installWindowOpenHandler() {
     import_electron2.app.on("web-contents-created", (_event, contents) => {
+      if (contents.getType() === "webview") {
+        const host = contents.hostWebContents;
+        if (host) {
+          contents.on("before-input-event", (event, input) => {
+            handleNativeNavigationKey(event, input, process.platform, (key) => {
+              host.send(NATIVE_NAVIGATION_KEY_CHANNEL, key);
+            });
+          });
+        }
+      }
       contents.setWindowOpenHandler(({ url }) => {
         if (isExternalOpenURL(url)) {
           if (process.env.TV_TEST_MODE === "true") {

package/dist/webview-bridge-preload.cjs

@@ -41,7 +41,6 @@ var documentGuid = makeBridgeGuid();
 function postBridgeReady() {
   import_electron.ipcRenderer.sendToHost(BRIDGE_CHANNEL, {
     type: "bridge-ready",
-    url: window.location.href,
     guid: documentGuid
   });
 }
@@ -88,85 +87,70 @@ function startProxyContentPoll() {
   const SLOW_POLL_MS = cadence?.slowMs ?? PRODUCTION_SLOW_POLL_MS;
   let baselineETag = null;
   let delayMs = NORMAL_POLL_MS;
-  let stopped = false;
-  const poll = () => {
-    void (async () => {
-      try {
-        const response = await window.fetch(capturedURL, { method: "HEAD" });
-        if (!response.ok) throw new Error("Artifact poll failed");
-        const etag = response.headers.get("ETag");
-        if (!etag) throw new Error("Artifact poll missing ETag");
-        delayMs = NORMAL_POLL_MS;
-        if (baselineETag === null) {
-          baselineETag = etag;
-        } else if (etag !== baselineETag) {
-          baselineETag = etag;
-          import_electron.ipcRenderer.sendToHost(BRIDGE_CHANNEL, { type: "proxy-content-changed" });
+  let generation = 0;
+  let active = false;
+  let queuedTimer = null;
+  let activeAbortController = null;
+  const stopPollLoop = () => {
+    if (!active) return;
+    active = false;
+    generation += 1;
+    if (queuedTimer !== null) {
+      window.clearTimeout(queuedTimer);
+      queuedTimer = null;
+    }
+    activeAbortController?.abort();
+    activeAbortController = null;
+  };
+  const startPollLoop = () => {
+    if (active) return;
+    active = true;
+    const loopGeneration = ++generation;
+    const poll = () => {
+      if (!active || loopGeneration !== generation) return;
+      queuedTimer = null;
+      const AbortControllerConstructor = window.AbortController;
+      const abortController = typeof AbortControllerConstructor === "function" ? new AbortControllerConstructor() : null;
+      activeAbortController = abortController;
+      void (async () => {
+        try {
+          const response = await window.fetch(capturedURL, {
+            method: "HEAD",
+            ...abortController ? { signal: abortController.signal } : {}
+          });
+          if (!active || loopGeneration !== generation) return;
+          if (!response.ok) throw new Error("Artifact poll failed");
+          const etag = response.headers.get("ETag");
+          if (!etag) throw new Error("Artifact poll missing ETag");
+          delayMs = NORMAL_POLL_MS;
+          if (baselineETag === null) {
+            baselineETag = etag;
+          } else if (etag !== baselineETag) {
+            baselineETag = etag;
+            import_electron.ipcRenderer.sendToHost(BRIDGE_CHANNEL, { type: "proxy-content-changed" });
+          }
+        } catch {
+          if (active && loopGeneration === generation) {
+            delayMs = Math.min(SLOW_POLL_MS, delayMs * 2);
+          }
+        } finally {
+          if (activeAbortController === abortController) {
+            activeAbortController = null;
+          }
+          if (active && loopGeneration === generation) {
+            queuedTimer = window.setTimeout(poll, delayMs);
+          }
         }
-      } catch {
-        delayMs = Math.min(SLOW_POLL_MS, delayMs * 2);
-      } finally {
-        if (!stopped) window.setTimeout(poll, delayMs);
-      }
-    })();
+      })();
+    };
+    poll();
   };
-  window.addEventListener("pagehide", () => {
-    stopped = true;
+  window.addEventListener("pagehide", stopPollLoop);
+  window.addEventListener("pageshow", (event) => {
+    if (event.persisted === true) {
+      startPollLoop();
+    }
   });
-  poll();
+  startPollLoop();
 }
 startProxyContentPoll();
-function isTextEditingTarget(target) {
-  if (!(target instanceof Element)) {
-    return false;
-  }
-  const editable = target.closest(
-    "input, textarea, select, [contenteditable], [role='textbox'], [role='searchbox'], [role='combobox'], [role='spinbutton'], [role='slider']"
-  );
-  if (!editable) {
-    return false;
-  }
-  if (editable.hasAttribute("contenteditable")) {
-    return editable.getAttribute("contenteditable")?.toLowerCase() !== "false";
-  }
-  return true;
-}
-window.addEventListener(
-  "keydown",
-  (event) => {
-    if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") {
-      return;
-    }
-    if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) {
-      return;
-    }
-    if (isTextEditingTarget(event.target)) {
-      return;
-    }
-    event.preventDefault();
-    import_electron.ipcRenderer.sendToHost(BRIDGE_CHANNEL, {
-      type: "filmstrip-key",
-      direction: event.key === "ArrowRight" ? 1 : -1
-    });
-  },
-  { capture: true }
-);
-window.addEventListener(
-  "wheel",
-  (event) => {
-    const usingShiftFallback = event.shiftKey && event.deltaX === 0 && event.deltaY !== 0;
-    const horizontalDelta = usingShiftFallback ? event.deltaY : event.deltaX;
-    const horizontalMagnitude = Math.abs(horizontalDelta);
-    const verticalMagnitude = usingShiftFallback ? 0 : Math.abs(event.deltaY);
-    if (horizontalMagnitude <= verticalMagnitude) {
-      return;
-    }
-    const payload = {
-      type: "wheel",
-      deltaX: horizontalDelta,
-      shiftKey: event.shiftKey
-    };
-    import_electron.ipcRenderer.sendToHost(BRIDGE_CHANNEL, payload);
-  },
-  { passive: false }
-);

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@telepath-computer/television-desktop",
   "productName": "Television",
-  "version": "0.1.206",
+  "version": "0.1.208",
   "license": "MIT",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.12.0"
   },
   "type": "module",
   "main": "dist/electron.cjs",
@@ -15,7 +15,9 @@
     "dist/**",
     "bin/**",
     "assets/**",
-    "scripts/rename-bundle.cjs"
+    "scripts/launcher-core.cjs",
+    "scripts/rename-bundle.cjs",
+    "scripts/branding-core.cjs"
   ],
   "exports": {
     ".": "./src/index.ts"
@@ -26,9 +28,10 @@
     "type-check": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "electron": "35.7.5"
+    "electron": "43.2.0"
   },
   "devDependencies": {
+    "@telepath-computer/television-artifact": "*",
     "@telepath-computer/television-shared": "*"
   }
 }

package/scripts/branding-core.cjs

@@ -0,0 +1,204 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const UPSTREAM_PATH = "Electron.app/Contents/MacOS/Electron";
+const BRANDED_PATH = "Television.app/Contents/MacOS/Television";
+const IDENTITY = {
+  CFBundleName: "Television",
+  CFBundleDisplayName: "Television",
+  CFBundleExecutable: "Television",
+  CFBundleIdentifier: "computer.telepath.television",
+};
+const LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+
+function runMacBranding(boundaries) {
+  if (boundaries.platform !== "darwin") return 0;
+
+  try {
+    const runtime = inspectRuntime(boundaries);
+    if (runtime.layout === "branded") {
+      refreshLaunchServices(boundaries, runtime.bundlePath);
+      return 0;
+    }
+    if (runtime.layout !== "upstream") {
+      throw new Error(runtime.reason);
+    }
+    if (fs.existsSync(runtime.brandedBundlePath)) {
+      throw new Error("the branded Electron bundle already exists beside the upstream runtime");
+    }
+
+    transformRuntime(boundaries, runtime);
+    const branded = inspectRuntime(boundaries);
+    if (branded.layout !== "branded") {
+      throw new Error(`the branded Electron runtime is invalid: ${branded.reason}`);
+    }
+    refreshLaunchServices(boundaries, branded.bundlePath);
+    return 0;
+  } catch (error) {
+    boundaries.writeStderr(`[television-desktop] could not prepare the Television bundle: ${errorMessage(error)}`);
+    return 1;
+  }
+}
+
+function inspectRuntime(boundaries) {
+  let packageRoot;
+  let targetVersion;
+  try {
+    const desktopManifest = readJSON(path.join(boundaries.desktopPackageDirectory, "package.json"));
+    targetVersion = desktopManifest.dependencies?.electron;
+    if (typeof targetVersion !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(targetVersion)) {
+      return invalid("the desktop Electron dependency is missing or is not an exact version");
+    }
+    packageRoot = boundaries.resolveElectronPackageRoot();
+    const packageManifest = readJSON(path.join(packageRoot, "package.json"));
+    if (packageManifest.version !== targetVersion) {
+      return invalid(`the Electron package version does not match ${targetVersion}`);
+    }
+  } catch (error) {
+    return invalid(`the Electron package could not be resolved: ${errorMessage(error)}`);
+  }
+
+  const dist = path.join(packageRoot, "dist");
+  const pathFile = path.join(packageRoot, "path.txt");
+  let recordedPath;
+  let recordedVersion;
+  try {
+    recordedPath = fs.readFileSync(pathFile, "utf8");
+    recordedVersion = fs.readFileSync(path.join(dist, "version"), "utf8");
+  } catch (error) {
+    return invalid(`the generated Electron runtime is incomplete: ${errorMessage(error)}`);
+  }
+  if (recordedVersion !== targetVersion) {
+    return invalid(`the generated Electron runtime version does not match ${targetVersion}`);
+  }
+
+  if (recordedPath === BRANDED_PATH) {
+    const bundlePath = path.join(dist, "Television.app");
+    const validity = inspectBundle(boundaries, bundlePath, "Television", IDENTITY);
+    return validity === null
+      ? { layout: "branded", packageRoot, pathFile, bundlePath }
+      : invalid(validity);
+  }
+  if (recordedPath === UPSTREAM_PATH) {
+    const bundlePath = path.join(dist, "Electron.app");
+    const validity = inspectBundle(boundaries, bundlePath, "Electron", { CFBundleExecutable: "Electron" });
+    return validity === null
+      ? {
+          layout: "upstream",
+          packageRoot,
+          pathFile,
+          bundlePath,
+          brandedBundlePath: path.join(dist, "Television.app"),
+        }
+      : invalid(validity);
+  }
+  return invalid(`path.txt contains an unexpected macOS executable path: ${JSON.stringify(recordedPath)}`);
+}
+
+function inspectBundle(boundaries, bundlePath, executableName, expectedIdentity) {
+  const contents = path.join(bundlePath, "Contents");
+  const executable = path.join(contents, "MacOS", executableName);
+  const plist = path.join(contents, "Info.plist");
+  const frameworks = path.join(contents, "Frameworks");
+  if (!executableIsValid(executable) || !regularFile(plist) || !nonemptyDirectory(frameworks)) {
+    return `the ${path.basename(bundlePath)} layout is incomplete`;
+  }
+  for (const [key, expected] of Object.entries(expectedIdentity)) {
+    const result = boundaries.runCommand("plutil", ["-extract", key, "raw", "-o", "-", plist]);
+    if (!commandSucceeded(result)) {
+      return `could not read ${key} from ${plist}: ${commandFailure(result)}`;
+    }
+    const actual = typeof result.stdout === "string" ? result.stdout.replace(/\r?\n$/, "") : "";
+    if (actual !== expected) {
+      return `${key} is ${JSON.stringify(actual)} instead of ${JSON.stringify(expected)}`;
+    }
+  }
+  return null;
+}
+
+function transformRuntime(boundaries, runtime) {
+  const brandedBundle = runtime.brandedBundlePath;
+  fs.renameSync(runtime.bundlePath, brandedBundle);
+
+  const contents = path.join(brandedBundle, "Contents");
+  fs.renameSync(
+    path.join(contents, "MacOS", "Electron"),
+    path.join(contents, "MacOS", "Television"),
+  );
+  fs.copyFileSync(
+    path.join(boundaries.desktopPackageDirectory, "assets", "icon.icns"),
+    path.join(contents, "Resources", "electron.icns"),
+  );
+
+  const plist = path.join(contents, "Info.plist");
+  for (const [key, value] of Object.entries(IDENTITY)) {
+    const result = boundaries.runCommand("plutil", ["-replace", key, "-string", value, plist]);
+    if (!commandSucceeded(result)) {
+      throw new Error(`could not set ${key} in ${plist}: ${commandFailure(result)}`);
+    }
+  }
+
+  const temporaryPathFile = path.join(runtime.packageRoot, "path.txt.tmp");
+  fs.writeFileSync(temporaryPathFile, BRANDED_PATH, { encoding: "utf8", flag: "wx" });
+  fs.renameSync(temporaryPathFile, runtime.pathFile);
+}
+
+function refreshLaunchServices(boundaries, bundlePath) {
+  const result = boundaries.runCommand(LSREGISTER, ["-f", bundlePath]);
+  if (!commandSucceeded(result)) {
+    boundaries.writeStderr(
+      `[television-desktop] warning: could not refresh LaunchServices: ${commandFailure(result)}`,
+    );
+  }
+}
+
+function commandSucceeded(result) {
+  return result?.error === undefined && result?.status === 0;
+}
+
+function commandFailure(result) {
+  if (result?.error !== undefined) return errorMessage(result.error);
+  return result?.status === null
+    ? "the command exited without a status"
+    : `the command exited with status ${result?.status}`;
+}
+
+function executableIsValid(file) {
+  try {
+    if (!fs.statSync(file).isFile()) return false;
+    fs.accessSync(file, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function regularFile(file) {
+  try {
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function nonemptyDirectory(directory) {
+  try {
+    return fs.statSync(directory).isDirectory() && fs.readdirSync(directory).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function readJSON(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function invalid(reason) {
+  return { layout: "invalid", reason };
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+module.exports = { runMacBranding };

package/scripts/launcher-core.cjs

@@ -0,0 +1,247 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const SETUP_MESSAGE = "[television-desktop] Preparing the Electron runtime. A download may be required; this can take a moment.";
+const DOWNLOAD_MESSAGE = "[television-desktop] Could not download the Electron runtime. Check your network connection and run tv-desktop again.";
+const INVALID_MESSAGE = "[television-desktop] The Electron runtime is incomplete or does not match this Television release.";
+const BRANDING_MESSAGE = "[television-desktop] Could not prepare the Television application bundle.";
+const REINSTALL_MESSAGE = "Reinstall it with: npm i -g @telepath-computer/television-desktop@latest";
+const BRANDED_IDENTITY = {
+  CFBundleName: "Television",
+  CFBundleDisplayName: "Television",
+  CFBundleExecutable: "Television",
+  CFBundleIdentifier: "computer.telepath.television",
+};
+
+async function runDesktopLauncher(userArgs, env, boundaries) {
+  try {
+    const packageRoot = boundaries.resolveElectronPackageRoot();
+    let state = inspectRuntime(packageRoot, boundaries);
+
+    if (state.kind === "absent") {
+      boundaries.writeStdout(SETUP_MESSAGE);
+      try {
+        boundaries.loadElectronResolver();
+      } catch {
+        boundaries.writeStderr(DOWNLOAD_MESSAGE);
+        return exit(1);
+      }
+      state = inspectRuntime(packageRoot, boundaries);
+    }
+
+    if (state.kind === "invalid" || state.kind === "absent") {
+      writeReinstallFailure(boundaries, INVALID_MESSAGE);
+      return exit(1);
+    }
+
+    if (boundaries.platform === "darwin" && state.kind === "upstream-macos") {
+      let brandingStatus;
+      try {
+        brandingStatus = boundaries.runBranding();
+      } catch {
+        writeReinstallFailure(boundaries, BRANDING_MESSAGE);
+        return exit(1);
+      }
+      if (brandingStatus !== 0) {
+        writeReinstallFailure(boundaries, BRANDING_MESSAGE);
+        return exit(1);
+      }
+      state = inspectRuntime(packageRoot, boundaries);
+      if (state.kind !== "branded-macos") {
+        writeReinstallFailure(boundaries, BRANDING_MESSAGE);
+        return exit(1);
+      }
+    }
+
+    if (state.kind !== "native" && state.kind !== "branded-macos") {
+      writeReinstallFailure(boundaries, INVALID_MESSAGE);
+      return exit(1);
+    }
+
+    const childEnv = { ...env };
+    delete childEnv.ELECTRON_RUN_AS_NODE;
+    const child = boundaries.spawnElectron(
+      state.executablePath,
+      [boundaries.desktopPackageDirectory, ...userArgs],
+      { env: childEnv, stdio: "inherit" },
+    );
+    return await childOutcome(child, boundaries);
+  } catch (error) {
+    boundaries.writeStderr(`[television-desktop] Could not start Television: ${errorDetail(error)}`);
+    return exit(1);
+  }
+}
+
+function inspectRuntime(packageRoot, boundaries) {
+  const dist = path.join(packageRoot, "dist");
+  const versionFile = path.join(dist, "version");
+  const pathFile = path.join(packageRoot, "path.txt");
+
+  if (runtimeIsAbsent(dist, versionFile, pathFile)) return { kind: "absent" };
+
+  let targetVersion;
+  let packageVersion;
+  let runtimeVersion;
+  let recordedPath;
+  try {
+    const desktopManifest = readJSON(path.join(boundaries.desktopPackageDirectory, "package.json"));
+    targetVersion = desktopManifest.dependencies?.electron;
+    if (typeof targetVersion !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(targetVersion)) {
+      return { kind: "invalid" };
+    }
+    packageVersion = readJSON(path.join(packageRoot, "package.json")).version;
+    runtimeVersion = readRegularFile(versionFile);
+    recordedPath = readRegularFile(pathFile);
+  } catch {
+    return { kind: "invalid" };
+  }
+  if (packageVersion !== targetVersion || runtimeVersion !== targetVersion) {
+    return { kind: "invalid" };
+  }
+
+  if (boundaries.platform === "darwin") {
+    return inspectMacRuntime(packageRoot, recordedPath, boundaries);
+  }
+  if (boundaries.platform === "linux" || boundaries.platform === "win32") {
+    const executableName = boundaries.platform === "win32" ? "electron.exe" : "electron";
+    const executablePath = path.join(dist, executableName);
+    return recordedPath === executableName && executableIsValid(executablePath)
+      ? { kind: "native", executablePath }
+      : { kind: "invalid" };
+  }
+  return { kind: "invalid" };
+}
+
+function inspectMacRuntime(packageRoot, recordedPath, boundaries) {
+  const dist = path.join(packageRoot, "dist");
+  if (recordedPath === "Television.app/Contents/MacOS/Television") {
+    const bundle = path.join(dist, "Television.app");
+    return macBundleIsValid(bundle, "Television", BRANDED_IDENTITY, boundaries)
+      ? {
+          kind: "branded-macos",
+          executablePath: path.join(bundle, "Contents", "MacOS", "Television"),
+        }
+      : { kind: "invalid" };
+  }
+  if (recordedPath === "Electron.app/Contents/MacOS/Electron") {
+    const bundle = path.join(dist, "Electron.app");
+    const brandedBundle = path.join(dist, "Television.app");
+    return !fs.existsSync(brandedBundle)
+      && macBundleIsValid(bundle, "Electron", { CFBundleExecutable: "Electron" }, boundaries)
+      ? {
+          kind: "upstream-macos",
+          executablePath: path.join(bundle, "Contents", "MacOS", "Electron"),
+        }
+      : { kind: "invalid" };
+  }
+  return { kind: "invalid" };
+}
+
+function macBundleIsValid(bundle, executableName, expectedIdentity, boundaries) {
+  const contents = path.join(bundle, "Contents");
+  const executable = path.join(contents, "MacOS", executableName);
+  const plist = path.join(contents, "Info.plist");
+  const frameworks = path.join(contents, "Frameworks");
+  if (!executableIsValid(executable) || !regularFile(plist) || !nonemptyDirectory(frameworks)) {
+    return false;
+  }
+  try {
+    return Object.entries(expectedIdentity).every(
+      ([key, expected]) => boundaries.readMacPlistValue(plist, key) === expected,
+    );
+  } catch {
+    return false;
+  }
+}
+
+function runtimeIsAbsent(dist, versionFile, pathFile) {
+  if (fs.existsSync(pathFile) || fs.existsSync(versionFile)) return false;
+  if (!fs.existsSync(dist)) return true;
+  try {
+    return fs.statSync(dist).isDirectory() && fs.readdirSync(dist).length === 0;
+  } catch {
+    return false;
+  }
+}
+
+function readRegularFile(file) {
+  if (!fs.statSync(file).isFile()) throw new Error(`${file} is not a regular file`);
+  return fs.readFileSync(file, "utf8");
+}
+
+function executableIsValid(file) {
+  try {
+    if (!fs.statSync(file).isFile()) return false;
+    fs.accessSync(file, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function regularFile(file) {
+  try {
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function nonemptyDirectory(directory) {
+  try {
+    return fs.statSync(directory).isDirectory() && fs.readdirSync(directory).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function childOutcome(child, boundaries) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (outcome) => {
+      if (settled) return;
+      settled = true;
+      child.removeListener("error", onError);
+      child.removeListener("exit", onExit);
+      resolve(outcome);
+    };
+    const onError = (error) => {
+      if (settled) return;
+      boundaries.writeStderr(`[television-desktop] Could not start Television: ${errorDetail(error)}`);
+      finish(exit(1));
+    };
+    const onExit = (code, signal) => {
+      if (settled) return;
+      if (signal) {
+        finish({ kind: "signal", signal });
+      } else if (Number.isInteger(code)) {
+        finish(exit(code));
+      } else {
+        boundaries.writeStderr("[television-desktop] Television exited without a status or signal.");
+        finish(exit(1));
+      }
+    };
+    child.once("error", onError);
+    child.once("exit", onExit);
+  });
+}
+
+function writeReinstallFailure(boundaries, message) {
+  boundaries.writeStderr(message);
+  boundaries.writeStderr(REINSTALL_MESSAGE);
+}
+
+function readJSON(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function errorDetail(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/\r?\n/g, " ");
+}
+
+function exit(code) {
+  return { kind: "exit", code };
+}
+
+module.exports = { runDesktopLauncher };

package/scripts/rename-bundle.cjs

@@ -1,65 +1,31 @@
 #!/usr/bin/env node
-// Renames the bundled Electron.app to Television.app (bundle + inner
-// executable + plist) so macOS labels the Dock and menu bar as
-// "Television" instead of "Electron". macOS reads the running-app name
-// from the bundle's filesystem identity; just editing Info.plist isn't
-// enough — the .app directory and Contents/MacOS/<exe> have to match.
-// Scoped to this package's resolved electron install. Idempotent; no-ops
-// once the rename is complete.
-//
-// Invoked lazily on first launch by bin/tv-desktop.cjs. We can't use an
-// npm `postinstall` hook because npm runs our package's postinstall
-// before electron's postinstall has downloaded Electron.app — the rename
-// has nothing to rename at install time.
+// Electron 43 installs its native runtime lazily. The desktop launcher invokes
+// this entry on its macOS branding path, and the core validates the complete
+// Electron runtime before changing its bundle identity.
 
-const { execFileSync } = require("node:child_process");
+const { spawnSync } = require("node:child_process");
+const { createRequire } = require("node:module");
 const path = require("node:path");
-const fs = require("node:fs");
-
-if (process.platform !== "darwin") process.exit(0);
-
-let electronEntry;
-try {
-  electronEntry = require.resolve("electron");
-} catch {
-  process.exit(0);
-}
-
-const NAME = "Television";
-const BUNDLE_ID = "computer.telepath.television";
-const distDir = path.join(path.dirname(electronEntry), "dist");
-const oldApp = path.join(distDir, "Electron.app");
-const newApp = path.join(distDir, `${NAME}.app`);
-const targetApp = fs.existsSync(newApp) ? newApp : oldApp;
-
-if (!fs.existsSync(targetApp)) process.exit(0);
-
-try {
-  if (targetApp === oldApp) fs.renameSync(oldApp, newApp);
-
-  const macosDir = path.join(newApp, "Contents", "MacOS");
-  const oldExe = path.join(macosDir, "Electron");
-  const newExe = path.join(macosDir, NAME);
-  if (fs.existsSync(oldExe) && !fs.existsSync(newExe)) {
-    fs.renameSync(oldExe, newExe);
-  }
-
-  const ourIcon = path.join(__dirname, "..", "assets", "icon.icns");
-  const bundleIcon = path.join(newApp, "Contents", "Resources", "electron.icns");
-  if (fs.existsSync(ourIcon) && fs.existsSync(path.dirname(bundleIcon))) {
-    fs.copyFileSync(ourIcon, bundleIcon);
-  }
-
-  const plist = path.join(newApp, "Contents", "Info.plist");
-  execFileSync("plutil", ["-replace", "CFBundleName", "-string", NAME, plist]);
-  execFileSync("plutil", ["-replace", "CFBundleDisplayName", "-string", NAME, plist]);
-  execFileSync("plutil", ["-replace", "CFBundleExecutable", "-string", NAME, plist]);
-  execFileSync("plutil", ["-replace", "CFBundleIdentifier", "-string", BUNDLE_ID, plist]);
-
-  execFileSync(
-    "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister",
-    ["-f", newApp],
-  );
-} catch (err) {
-  console.warn(`[television-desktop] could not rename Electron bundle: ${err.message}`);
-}
+const { runMacBranding } = require("./branding-core.cjs");
+
+const desktopPackageDirectory = path.join(__dirname, "..");
+const requireFromDesktop = createRequire(path.join(desktopPackageDirectory, "package.json"));
+
+process.exitCode = runMacBranding({
+  platform: process.platform,
+  desktopPackageDirectory,
+  resolveElectronPackageRoot() {
+    return path.dirname(requireFromDesktop.resolve("electron/package.json"));
+  },
+  runCommand(command, args) {
+    const result = spawnSync(command, args, { encoding: "utf8" });
+    return {
+      status: result.status,
+      stdout: result.stdout,
+      error: result.error,
+    };
+  },
+  writeStderr(line) {
+    process.stderr.write(`${line}\n`);
+  },
+});