@materialwebunofficial/antigravity-themes 1.0.5 → 1.0.13

package/lib/asar.mjs

@@ -0,0 +1,163 @@
+// Electron asar archives: just enough for the native install, with no package
+// and no network. An archive is a size field and a header (two Chromium
+// Pickles; the header holds JSON), then the files back to back; files marked
+// "unpacked" live beside it in <archive>.unpacked/ instead.
+//
+// Electron's own Node (ELECTRON_RUN_AS_NODE, how Antigravity runs a sidecar)
+// shows an archive as a folder through fs; process.noAsar turns that off so
+// the archive reads as the file it is.
+import { createHash } from 'node:crypto';
+import {
+  closeSync, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, writeSync,
+} from 'node:fs';
+import path from 'node:path';
+
+process.noAsar = true;
+
+const BLOCK = 4 * 1024 * 1024;   // integrity block size, as @electron/asar
+
+export function readHeader(archive) {
+  const fd = openSync(archive, 'r');
+  try {
+    const size = Buffer.alloc(8);
+    readSync(fd, size, 0, 8, 0);
+    const headerSize = size.readUInt32LE(4);
+    const pickle = Buffer.alloc(headerSize);
+    readSync(fd, pickle, 0, headerSize, 8);
+    const length = pickle.readUInt32LE(4);
+    return { header: JSON.parse(pickle.toString('utf8', 8, 8 + length)), base: 8 + headerSize };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// The entry for a path inside the archive ('dist/preload.js'), or null
+function entryAt(header, file) {
+  let node = header;
+  for (const part of file.split(/[\\/]/)) {
+    node = node?.files?.[part];
+    if (!node) return null;
+  }
+  return node;
+}
+
+function readEntry(fd, base, entry) {
+  const buffer = Buffer.alloc(entry.size);
+  if (entry.size) readSync(fd, buffer, 0, entry.size, base + Number(entry.offset));
+  return buffer;
+}
+
+// One file's bytes, read without unpacking the rest
+export function readFile(archive, file) {
+  const { header, base } = readHeader(archive);
+  const entry = entryAt(header, file);
+  if (!entry || entry.files || entry.link) throw new Error(`${file} is not a file in ${archive}`);
+  if (entry.unpacked) return readFileSync(path.join(`${archive}.unpacked`, file));
+  const fd = openSync(archive, 'r');
+  try { return readEntry(fd, base, entry); } finally { closeSync(fd); }
+}
+
+// Every file into dest, unpacked ones copied from <archive>.unpacked.
+// Links become copies of what they point to.
+export function extract(archive, dest) {
+  const { header, base } = readHeader(archive);
+  const unpacked = `${archive}.unpacked`;
+  const links = [];
+  const fd = openSync(archive, 'r');
+  try {
+    const walk = (node, rel) => {
+      for (const [name, entry] of Object.entries(node.files)) {
+        const file = rel ? `${rel}/${name}` : name;
+        const out = path.join(dest, file);
+        if (entry.files) {
+          mkdirSync(out, { recursive: true });
+          walk(entry, file);
+        } else if (entry.link) {
+          links.push([out, path.join(dest, entry.link)]);
+        } else if (entry.unpacked) {
+          mkdirSync(path.dirname(out), { recursive: true });
+          copyFileSync(path.join(unpacked, file), out);
+        } else {
+          mkdirSync(path.dirname(out), { recursive: true });
+          const out_fd = openSync(out, 'w');
+          try { writeSync(out_fd, readEntry(fd, base, entry)); } finally { closeSync(out_fd); }
+        }
+      }
+    };
+    mkdirSync(dest, { recursive: true });
+    walk(header, '');
+  } finally {
+    closeSync(fd);
+  }
+  for (const [out, target] of links) {
+    if (existsSync(target)) copyFileSync(target, out);
+  }
+}
+
+const sha256 = (buffer) => createHash('sha256').update(buffer).digest('hex');
+function integrity(buffer) {
+  const blocks = [];
+  for (let i = 0; i < buffer.length; i += BLOCK) blocks.push(sha256(buffer.subarray(i, i + BLOCK)));
+  return { algorithm: 'SHA256', hash: sha256(buffer), blockSize: BLOCK, blocks };
+}
+
+// The archive again with some files' contents replaced ({ 'dist/main.js':
+// Buffer }): same entries, order and unpacked files; offsets, sizes and
+// integrity follow the new contents. Written beside it, then swapped in.
+export function rewrite(archive, replacements) {
+  const { header, base } = readHeader(archive);
+  for (const file of Object.keys(replacements)) {
+    const entry = entryAt(header, file);
+    if (!entry || entry.files || entry.link || entry.unpacked) throw new Error(`cannot replace ${file} in ${archive}`);
+  }
+  const chunks = [];
+  let offset = 0;
+  const fd = openSync(archive, 'r');
+  try {
+    const walk = (node, rel) => {
+      for (const [name, entry] of Object.entries(node.files)) {
+        const file = rel ? `${rel}/${name}` : name;
+        if (entry.files) { walk(entry, file); continue; }
+        if (entry.link || entry.unpacked) continue;
+        const data = replacements[file] ?? readEntry(fd, base, entry);
+        if (replacements[file]) {
+          entry.size = data.length;
+          entry.integrity = integrity(data);
+        }
+        entry.offset = String(offset);
+        offset += data.length;
+        chunks.push(data);
+      }
+    };
+    walk(header, '');
+  } finally {
+    closeSync(fd);
+  }
+  const json = Buffer.from(JSON.stringify(header), 'utf8');
+  const padded = (json.length + 3) & ~3;
+  const headerPickle = Buffer.alloc(8 + padded);
+  headerPickle.writeUInt32LE(4 + padded, 0);
+  headerPickle.writeUInt32LE(json.length, 4);
+  json.copy(headerPickle, 8);
+  const sizePickle = Buffer.alloc(8);
+  sizePickle.writeUInt32LE(4, 0);
+  sizePickle.writeUInt32LE(headerPickle.length, 4);
+
+  const temp = `${archive}.agy-tmp`;
+  const out = openSync(temp, 'w');
+  try {
+    writeSync(out, sizePickle);
+    writeSync(out, headerPickle);
+    for (const chunk of chunks) writeSync(out, chunk);
+  } finally {
+    closeSync(out);
+  }
+  try {
+    renameSync(temp, archive);
+  } catch (err) {
+    rmSync(temp, { force: true });   // in use (the app is running): leave the archive as it was
+    throw err;
+  }
+}
+
+export const removeTree = (dir) => rmSync(dir, { recursive: true, force: true, maxRetries: 3 });

package/lib/bundle.mjs

@@ -1,7 +1,14 @@
-// Builds the script that runs inside Antigravity: the vendored md3e-web
-// components, the theme modules and the theme host, started with a bundle
-// read from themes/index.json (each theme's CSS, its fonts as base64, and
-// the choices in the Theme menu).
+// Builds the scripts that run inside Antigravity.
+//
+// pageScript: the window's script. The vendored md3e-web components, the
+// theme modules and the theme host, started with a bundle read from
+// themes/index.json (each theme's CSS, its fonts as base64, and the choices
+// in the Theme menu).
+//
+// frameScript: the script for sidecar frames (Swarm and other plugin panes,
+// cross-origin plugin:// iframes). Only the frame host and each theme's frame
+// stylesheet: a frame never parses the window's CSS, components or fonts.
+import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -19,13 +26,21 @@ const MODULES = [
   'src/theme-host.js',
 ];
 
+// What <md-loading-indicator> needs out of vendor/md3e/components.js (its
+// modules sit there in dependency order, one "// ---- name ----" block each)
+const FRAME_COMPONENT = 'components/md-loading-indicator.js';
+
+const readThemes = (themesDir, map) => {
+  const out = {};
+  for (const [id, files] of Object.entries(map ?? {})) {
+    out[id] = [].concat(files).map((file) => readFileSync(path.join(themesDir, file), 'utf8')).join('\n');
+  }
+  return out;
+};
+
 export function loadBundle(root = ROOT) {
   const themesDir = path.join(root, 'themes');
   const index = JSON.parse(readFileSync(path.join(themesDir, 'index.json'), 'utf8'));
-  const themes = {};
-  for (const [id, files] of Object.entries(index.themes)) {
-    themes[id] = [].concat(files).map((file) => readFileSync(path.join(themesDir, file), 'utf8')).join('\n');
-  }
   const fonts = {};
   for (const [id, list] of Object.entries(index.fonts ?? {})) {
     fonts[id] = list.map(({ file, ...descriptors }) => ({
@@ -33,17 +48,21 @@ export function loadBundle(root = ROOT) {
       data: readFileSync(path.join(themesDir, file)).toString('base64'),
     }));
   }
-  return { default: index.default, themes, fonts, ripple: index.ripple ?? [], options: index.options };
+  return { default: index.default, themes: readThemes(themesDir, index.themes), fonts, ripple: index.ripple ?? [], options: index.options };
 }
 
 // On a new document the script runs before the parser has created <html>,
 // so it waits for that element; the host then waits for the rest itself.
-export function pageScript(root = ROOT) {
-  const parts = MODULES.map((file) => readFileSync(path.join(root, file), 'utf8'));
-  return `(() => {
+// The same script can reach a document twice (the native install and a
+// background process on the same version, or a reconnect): the second run
+// stops at the flag instead of evaluating it all again. A host clears the
+// flag when it is disposed.
+const hashOf = (text) => JSON.stringify(createHash('sha1').update(text).digest('hex').slice(0, 12));
+const whenRooted = (body, flag, hash = hashOf(body)) => `(() => {
+if (window.${flag} === ${hash}) return;
+window.${flag} = ${hash};
 const start = () => {
-${parts.join('\n;')}
-;agyThemeHost(${JSON.stringify(loadBundle(root))});
+${body}
 };
 if (document.documentElement) start();
 else new MutationObserver((_, observer) => {
@@ -52,17 +71,51 @@ else new MutationObserver((_, observer) => {
   start();
 }).observe(document, { childList: true });
 })();`;
+
+export function pageScript(root = ROOT) {
+  const parts = MODULES.map((file) => readFileSync(path.join(root, file), 'utf8'));
+  return whenRooted(`${parts.join('\n;')}
+;agyThemeHost(${JSON.stringify(loadBundle(root))});`, '__agyPageScript');
+}
+
+// The component modules up to and including the one asked for, as a function
+// body that defines the element. Run only when a theme needs it.
+function componentSlice(root, last) {
+  const source = readFileSync(path.join(root, 'vendor/md3e/components.js'), 'utf8');
+  const first = source.indexOf('\n// ---- ');
+  const marker = `\n// ---- ${last} ----`;
+  const at = source.indexOf(marker);
+  if (first < 0 || at < 0) throw new Error(`vendor/md3e/components.js has no module ${last}`);
+  const next = source.indexOf('\n// ---- ', at + marker.length);
+  return `'use strict';\nconst __md3e = {};${source.slice(first, next < 0 ? source.lastIndexOf('})();') : next)}`;
+}
+
+export function frameScript(root = ROOT) {
+  const themesDir = path.join(root, 'themes');
+  const index = JSON.parse(readFileSync(path.join(themesDir, 'index.json'), 'utf8'));
+  const host = readFileSync(path.join(root, 'src/frame-host.js'), 'utf8');
+  const bundle = JSON.stringify({ frames: readThemes(themesDir, index.frames), fonts: Object.keys(index.fonts ?? {}) });
+  return whenRooted(`${host}
+;agyFrameHost(Object.assign(${bundle}, { md3e: () => {
+${componentSlice(root, FRAME_COMPONENT)}
+} }));`, '__agyFrameScript');
 }
 
-// Undoes everything the page script did in that window
+// Sidecar frames are served from this scheme (the app's customScheme.js)
+export const FRAME_SCHEME = 'plugin://';
+export const isFrameUrl = (url) => typeof url === 'string' && url.startsWith(FRAME_SCHEME);
+
+// Undoes everything the scripts did in that window or frame
 export const REMOVE_SCRIPT = `(() => {
   window.__agyThemeHost?.dispose();
+  window.__agyFrameHost?.dispose();
   document.getElementById('agy-theme-css')?.remove();
   document.documentElement?.removeAttribute('data-agy-theme');
 })();`;
 
-// The theme host's version and theme in a window, or null without one
-export const PROBE_SCRIPT = `JSON.stringify(window.__agyThemeHost ? { version: window.__agyThemeHost.version, theme: window.__agyThemeHost.get() } : null)`;
+// The theme host's version and theme in a window (or the frame host's in a
+// sidecar frame), or null without one
+export const PROBE_SCRIPT = `JSON.stringify(window.__agyThemeHost ? { version: window.__agyThemeHost.version, theme: window.__agyThemeHost.get() } : window.__agyFrameHost ? { version: window.__agyFrameHost.version, theme: window.__agyFrameHost.get(), frame: true } : null)`;
 
 export const selectScript = (key) => `(() => {
   const host = window.__agyThemeHost;

package/lib/injector.mjs

@@ -3,11 +3,28 @@
 // sent anywhere else, and no app file is changed: the theme lives in the
 // open windows, and a script registered for each window's next document
 // brings it back after a reload while the connection lasts.
+//
+// A script is either one source for every target or a function of the
+// target: the app's own windows take the page script, sidecar frames
+// (plugin://) the frame script, and nothing else is touched: not the web pages
+// of the agent's browser, not a sandboxed srcdoc inside a sidecar.
 import { readFileSync } from 'node:fs';
 import { portFile } from './paths.mjs';
+import { isFrameUrl } from './bundle.mjs';
 
 const TARGET_TYPES = new Set(['page', 'webview', 'iframe']);
 
+// The app's windows are served by its language server on 127.0.0.1 (https)
+const APP_URL = new RegExp(String.raw`^https://(127\.0\.0\.1|localhost):\d+/`);
+const isAppUrl = (url) => typeof url === 'string' && APP_URL.test(url);
+
+// { page, frame } -> the source for one target, or null to leave it alone
+export const scriptFor = ({ page, frame }) => (target) => {
+  if (target.type === 'iframe') return isFrameUrl(target.url) ? frame : null;
+  return target.type === 'page' && isAppUrl(target.url) ? page : null;
+};
+const sourceFor = (script, target) => (typeof script === 'function' ? script(target) : script);
+
 export function readPort() {
   const file = portFile();
   let text;
@@ -98,10 +115,12 @@ export class Session {
 export async function evaluateEverywhere(script, port = readPort()) {
   const results = [];
   for (const target of await listTargets(port)) {
+    const source = sourceFor(script, target);
+    if (source == null) continue;
     const session = new Session(target);
     try {
       await session.open();
-      results.push({ url: target.url, value: await session.evaluate(script) });
+      results.push({ url: target.url, value: await session.evaluate(source) });
     } catch (err) {
       results.push({ url: target.url, error: err.message });
     } finally {
@@ -114,11 +133,14 @@ export async function evaluateEverywhere(script, port = readPort()) {
 // The long-running part: themes every window Antigravity opens, keeps the
 // theme across reloads, follows the port when the app restarts, and waits
 // while it is closed. getSource() is read again when reload() is called.
-export function watch({ getSource, log = () => {} }) {
+// With onGone it does not wait: once the app is closed (or never answers) it
+// stops and calls onGone, for a caller that lives only as long as the app.
+export function watch({ getSource, log = () => {}, onGone = null }) {
   const sessions = new Map();   // target id -> Session
   let port = null;
   let source = getSource();
   let waiting = false;
+  let found = false, misses = 0;
 
   function followPort() {
     const next = readPort();
@@ -132,12 +154,14 @@ export function watch({ getSource, log = () => {} }) {
   async function attachNew() {
     for (const target of await listTargets(port)) {
       if (sessions.has(target.id)) continue;
+      const script = sourceFor(source, target);
+      if (script == null) continue;
       const session = new Session(target);
       sessions.set(target.id, session);
       session.onclose = () => sessions.delete(target.id);
       try {
         await session.open();
-        await session.apply(source);
+        await session.apply(script);
         log(`themed ${target.type} ${target.url}`);
       } catch (err) {
         log(`${target.url}: ${err.message}`);
@@ -152,19 +176,26 @@ export function watch({ getSource, log = () => {} }) {
       await attachNew();
       if (waiting) log(`Antigravity found on port ${port}`);
       waiting = false;
+      found = true;
+      misses = 0;
     } catch (err) {
+      if (onGone && (found || ++misses >= 15)) {
+        log(`Antigravity is gone (${err.message})`);
+        api.stop();
+        onGone();
+        return;
+      }
       if (!waiting) log(`waiting for Antigravity (${err.message})`);
       waiting = true;
     }
   }
 
   const timer = setInterval(tick, 2000);
-  tick();
-  return {
+  const api = {
     async reload() {
       source = getSource();
       for (const session of sessions.values()) {
-        try { await session.apply(source); } catch (err) { log(`reload failed for ${session.target.url}: ${err.message}`); }
+        try { await session.apply(sourceFor(source, session.target)); } catch (err) { log(`reload failed for ${session.target.url}: ${err.message}`); }
       }
       log(`reloaded into ${sessions.size} window(s)`);
     },
@@ -173,4 +204,6 @@ export function watch({ getSource, log = () => {} }) {
       for (const session of sessions.values()) session.close();
     },
   };
+  tick();
+  return api;
 }

package/lib/keeper.mjs

@@ -0,0 +1,73 @@
+// The keeper: a one-shot sidecar that Antigravity starts with every launch,
+// from the plugin this tool installs (~/.gemini/config/plugins/
+// antigravity-themes, outside the app's install folder, so an update leaves it
+// alone). It keeps the native install in place:
+//
+// - everything current (the usual start): it exits at once;
+// - an Antigravity update replaced resources/ and resources/app with it: it
+//   extracts the new app.asar and patches it for the next start, and, since
+//   this start ran without the patch, themes the open windows over the app's
+//   DevTools port and keeps them themed until the app closes;
+// - the patch holds an older build of the scripts: it patches again and
+//   applies the new scripts to the open windows once.
+//
+// Antigravity runs it with its own Node (ELECTRON_RUN_AS_NODE). Its log is
+// keeper.log in the sidecar's data folder.
+import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { ROOT, pageScript, frameScript } from './bundle.mjs';
+import { appState, ensureApp, patchApp } from './native.mjs';
+import { evaluateEverywhere, scriptFor, watch } from './injector.mjs';
+import { appResourcesDir, installDir } from './paths.mjs';
+
+// Run by the app, the keeper is the app's own executable in Node mode.
+// AGY_THEMES_RESOURCES points elsewhere (tests).
+export function resourcesDir() {
+  if (process.env.AGY_THEMES_RESOURCES) return process.env.AGY_THEMES_RESOURCES;
+  const exe = process.execPath;
+  if (/^antigravity(\.exe)?$/i.test(path.basename(exe))) return path.join(path.dirname(exe), 'resources');
+  return appResourcesDir();
+}
+
+function logger() {
+  const dir = process.env.ANTIGRAVITY_EXECUTABLE_DATA_DIR || installDir();
+  const file = path.join(dir, 'keeper.log');
+  try {
+    mkdirSync(dir, { recursive: true });
+    if (statSync(file).size > 256 * 1024) writeFileSync(file, '');
+  } catch { /* no log yet */ }
+  return (line) => {
+    const entry = `${new Date().toISOString()} ${line}`;
+    console.log(entry);
+    try { appendFileSync(file, `${entry}\n`); } catch { /* read-only data folder: stdout only */ }
+  };
+}
+
+export async function runKeeper(root = ROOT) {
+  const log = logger();
+  try {
+    const { build } = JSON.parse(readFileSync(path.join(root, 'build.json'), 'utf8'));
+    const resources = resourcesDir();
+    const state = appState(resources);
+    if (state.extractedVersion && state.extractedVersion === state.appVersion && state.stamp?.build === build) {
+      log(`current: app ${state.appVersion}, build ${build}`);
+      return;
+    }
+    const page = pageScript(root), frame = frameScript(root);
+    const extracted = ensureApp(resources);
+    patchApp(state.appDir, { page, frame, build });
+    log(`${extracted ? 'extracted and patched' : 'patched'} app ${appState(resources).appVersion} with build ${build}`);
+    const scripts = scriptFor({ page, frame });
+    if (!extracted) {
+      const results = await evaluateEverywhere(scripts).catch((err) => { log(`not applied to the open windows: ${err.message}`); return []; });
+      if (results.length) log(`applied to ${results.filter((r) => !r.error).length} open window(s)`);
+      return;
+    }
+    // This start loaded the app without the patch
+    await new Promise((resolve) => watch({ getSource: () => scripts, log, onGone: resolve }));
+    log('app closed');
+  } catch (err) {
+    log(`failed: ${err.stack || err.message}`);
+    process.exitCode = 1;
+  }
+}

package/lib/native.mjs

@@ -0,0 +1,165 @@
+// The native install: the scripts are written into Antigravity's own files,
+// so no process has to stay running.
+//
+// - resources/app is the app extracted from resources/app.asar. Electron loads
+//   that folder ahead of the archive, so the archive itself stays the app's
+//   own and an update can replace it.
+// - dist/preload.js runs in every window: it evaluates the page script in the
+//   window's main world.
+// - dist/main.js gets a listener for sidecar frames. A preload does not run in
+//   subframes, and a sidecar pane (Swarm) is a cross-origin plugin:// iframe,
+//   so the main process evaluates the frame script in it as soon as its
+//   document commits.
+// - agy-themes.json in resources/app records which build of the scripts is in
+//   it and which app version it came from, for the keeper (keeper.mjs).
+//
+// Each patch is everything after its marker line: patching again replaces it,
+// and cutting the file at the marker restores the original.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { FRAME_SCHEME } from './bundle.mjs';
+import { extract, readFile, removeTree, rewrite } from './asar.mjs';
+
+export const PRELOAD_MARKER = '// Antigravity Native Theme Injection (Zero background processes)';
+export const MAIN_MARKER = '// Antigravity Native Theme Injection: sidecar frames';
+const STAMP = 'agy-themes.json';
+const PATCHED = { 'dist/preload.js': PRELOAD_MARKER, 'dist/main.js': MAIN_MARKER };
+
+export const buildId = (page, frame) => createHash('sha1').update(page).update('\0').update(frame).digest('hex').slice(0, 16);
+
+// The text before the marker: the file as the app shipped it
+export function cut(text, marker) {
+  const at = text.indexOf(marker);
+  return at === -1 ? text : `${text.slice(0, at).trimEnd()}\n`;
+}
+
+function patchFile(file, marker, block) {
+  writeFileSync(file, `${cut(readFileSync(file, 'utf8'), marker)}\n\n${marker}\n${block}\n`, 'utf8');
+}
+
+const preloadBlock = (page) => `(function() {
+  try {
+    const electron = require('electron');
+    if (electron && electron.webFrame && typeof electron.webFrame.executeJavaScript === 'function') {
+      electron.webFrame.executeJavaScript(${JSON.stringify(page)});
+    }
+  } catch (err) {
+    console.error('[antigravity-themes] Injection error:', err);
+  }
+})();`;
+
+const mainBlock = (frame) => `(function() {
+  try {
+    const { app, webFrameMain } = require('electron');
+    const source = ${JSON.stringify(frame)};
+    app.on('web-contents-created', (_event, contents) => {
+      contents.on('did-frame-navigate', (_e, url, _code, _status, isMainFrame, processId, routingId) => {
+        if (isMainFrame || typeof url !== 'string' || !url.startsWith(${JSON.stringify(FRAME_SCHEME)})) return;
+        try {
+          const frame = webFrameMain.fromId(processId, routingId);
+          if (frame) frame.executeJavaScript(source).catch(() => {});
+        } catch (err) {
+          // the frame went away while its document was committing
+        }
+      });
+    });
+  } catch (err) {
+    console.error('[antigravity-themes] Frame injection error:', err);
+  }
+})();`;
+
+const readJson = (file) => {
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
+};
+
+// appDir: the extracted app (resources/app)
+export function patchApp(appDir, { page, frame, build = buildId(page, frame) }) {
+  const preload = path.join(appDir, 'dist', 'preload.js');
+  const main = path.join(appDir, 'dist', 'main.js');
+  patchFile(preload, PRELOAD_MARKER, preloadBlock(page));
+  patchFile(main, MAIN_MARKER, mainBlock(frame));
+  const appVersion = readJson(path.join(appDir, 'package.json'))?.version ?? null;
+  writeFileSync(path.join(appDir, STAMP), `${JSON.stringify({ build, appVersion }, null, 2)}\n`);
+  return { preload, main, build, appVersion };
+}
+
+// What is installed: the app's version (in its archive), the extracted copy's
+// version, and the stamp of the scripts in it
+export function appState(resources) {
+  const archive = path.join(resources, 'app.asar');
+  const appDir = path.join(resources, 'app');
+  let appVersion = null;
+  try { appVersion = JSON.parse(readFile(archive, 'package.json')).version; } catch { /* no archive */ }
+  return {
+    archive,
+    appDir,
+    appVersion,
+    extractedVersion: readJson(path.join(appDir, 'package.json'))?.version ?? null,
+    stamp: readJson(path.join(appDir, STAMP)),
+  };
+}
+
+// resources/app from the app's archive, unless it already holds this version.
+// Extracted beside it and swapped in, so the app never finds half a folder.
+// Returns true when it was (re)extracted.
+export function ensureApp(resources) {
+  const state = appState(resources);
+  if (!state.appVersion) throw new Error(`${state.archive} was not found or is not an app archive`);
+  if (state.extractedVersion === state.appVersion) return false;
+  const fresh = `${state.appDir}.agy-new`;
+  removeTree(fresh);
+  extract(state.archive, fresh);
+  for (const [file, marker] of Object.entries(PATCHED)) {   // an archive patched by an earlier install
+    const full = path.join(fresh, file);
+    if (existsSync(full)) writeFileSync(full, cut(readFileSync(full, 'utf8'), marker), 'utf8');
+  }
+  if (existsSync(state.appDir)) {
+    const old = `${state.appDir}.agy-old`;
+    removeTree(old);
+    renameSync(state.appDir, old);
+    renameSync(fresh, state.appDir);
+    removeTree(old);
+  } else {
+    renameSync(fresh, state.appDir);
+  }
+  return true;
+}
+
+// Earlier builds of this tool (before 1.0.13) also patched app.asar itself:
+// put the app's own preload and main back in it. Returns true when it did.
+export function restoreArchive(resources) {
+  const archive = path.join(resources, 'app.asar');
+  if (!existsSync(archive)) return false;
+  const replacements = {};
+  for (const [file, marker] of Object.entries(PATCHED)) {
+    const text = readFile(archive, file).toString('utf8');
+    if (text.includes(marker)) replacements[file] = Buffer.from(cut(text, marker), 'utf8');
+  }
+  if (!Object.keys(replacements).length) return false;
+  rewrite(archive, replacements);
+  return true;
+}
+
+// The app's preload and main without the patches, in place (uninstalling
+// while the app runs: it keeps loading this folder until it restarts)
+export function unpatchApp(appDir) {
+  for (const [file, marker] of Object.entries(PATCHED)) {
+    const full = path.join(appDir, file);
+    if (existsSync(full)) writeFileSync(full, cut(readFileSync(full, 'utf8'), marker), 'utf8');
+  }
+  removeTree(path.join(appDir, STAMP));
+}
+
+// app.asar.patched (and its .unpacked folder) from the hand-made builds that
+// preceded the keeper: unused, and holding an old copy of the app
+export function removeLegacyArchive(resources) {
+  const legacy = path.join(resources, 'app.asar.patched');
+  if (!existsSync(legacy)) return false;
+  let ours = false;
+  try { ours = readFile(legacy, 'dist/preload.js').toString('utf8').includes(PRELOAD_MARKER); } catch { /* not an archive */ }
+  if (!ours) return false;
+  removeTree(legacy);
+  removeTree(`${legacy}.unpacked`);
+  return true;
+}

package/lib/paths.mjs

@@ -14,8 +14,9 @@ export function appDataDir() {
 }
 
 // Antigravity starts with --remote-debugging-port=0 and writes the port it
-// got here (first line), anew on every launch
-export const portFile = () => path.join(appDataDir(), 'DevToolsActivePort');
+// got here (first line), anew on every launch. AGY_THEMES_PORT_FILE points
+// elsewhere (tests).
+export const portFile = () => process.env.AGY_THEMES_PORT_FILE || path.join(appDataDir(), 'DevToolsActivePort');
 
 export function installDir() {
   if (process.platform === 'win32') return path.join(process.env.LOCALAPPDATA ?? path.join(home, 'AppData', 'Local'), 'antigravity-themes');