@shimabell06/cloud-arch-icon-browser 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @shimabell06/cloud-arch-icon-browser
 
+## 0.3.0
+
+### Minor Changes
+
+- 46753f3: Add an Experimental Windows PowerPoint Copy all workflow for Tray items through a capability-scoped localhost bridge, with bounded transient PNG handling and perceived-size normalization. Physical Windows/PowerPoint paste validation remains tracked by #57 and is not yet a formal compatibility claim.
+- 9aeba15: Use a stable canonical localhost origin for packaged runs, reuse an already-running matching local instance, and let supported browsers reopen a previously validated local ZIP through a persisted File System Access handle without storing package bytes.
+- 2e1045e: Add a session-only Tray with quantity/order controls, multi-select and drag collection, reusable locally persisted Saved Sets, recently-used history, and frequently-used shortcuts.
+
+### Patch Changes
+
+- 2666a3e: Reduce initial and scroll-time icon preview latency with shared prefetch observation and bounded viewport-prioritized preview work.
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -17,21 +17,43 @@ Cloud Arch Icon Browser is an independent open-source project. It is not affilia
 
 3. Choose the downloaded ZIP in the browser.
 
-The command starts a temporary localhost server bound to `127.0.0.1` and opens the app in your default browser. The selected ZIP is processed locally and is not uploaded or persisted by the application.
+The command serves the app from the stable local origin `http://127.0.0.1:41731/` and opens it in your default browser. A second invocation reuses the same running app; if another process occupies that port, the CLI reports an error rather than switching origins. The selected ZIP is processed locally and its bytes are never uploaded or copied into application storage.
+
+On browsers that support the File System Access API, a successfully validated selection can remember only the local file handle in IndexedDB. A later launch can use `Open previous ZIP` to request/read that file under normal browser permission rules, and `Forget previous ZIP reference` removes the handle. The app does not trigger a file-permission prompt automatically on page load. Unsupported browsers continue to use the normal ZIP picker.
 
 ## Features
 
 - Fast search across icon names, original filenames, and category paths.
 - Category browsing with explicit search filter chips.
-- Favorites, recent icons, recent searches, and Grid / Compact views.
+- Favorites, recently used icons, recent searches, Frequently used shortcuts, Tray, Saved Sets, and Grid / Compact views.
 - Centered icon details with real package metadata.
 - Copy icons as transparent 512×512 PNG images for compatible clipboard workflows such as Windows PowerPoint and Excel.
-- Copy SVG where supported or download the original SVG with its original filename.
+- Copy original SVG source text where supported or download the original SVG with its original filename.
+- Experimental Windows PowerPoint `Copy all` from the Tray in the packaged `npx` runtime, preserving Tray order and quantities without a flattened-image fallback.
 - System, Light, and Dark themes with responsive keyboard-accessible navigation.
-- Local-only package processing with no automatic runtime network access.
+- Local-only package processing with no automatic runtime network access; supported browsers can remember only a local file reference for the previous ZIP.
 
 `Copy image` depends on browser Clipboard API support and permission. If image clipboard writes are unavailable or denied, the app reports the failure and the original SVG remains available for download.
 
+### Experimental PowerPoint Copy all
+
+On Windows, the packaged `npx` runtime exposes an explicitly Experimental `Copy all` action in the Tray. It prepares up to 36 transient 512×512 PNG representations, preserves Tray order and quantities, asks desktop PowerPoint to copy them as a multi-shape selection, and then lets you paste once in PowerPoint. Generated PNGs and temporary Office files stay local and are deleted after the operation. There is no cloud service and no flattened combined-image fallback.
+
+This workflow is **not yet formally supported** because real-machine Windows 11 + current Chromium + Microsoft 365 PowerPoint validation is still pending. The UI shows an Experimental warning on first use. If the later validation fails, the feature will be disabled or removed rather than replaced by a flattened image.
+
+The feature is enabled by default for evaluation. To disable it locally, run this in the app's browser developer console and reload:
+
+```js
+localStorage.setItem(
+  "cloud-arch-icon-browser:feature:powerpoint-copy-all",
+  "off",
+);
+```
+
+Delete that key (or set it to `on`) to return to the built-in default. The existing single-icon `Copy image` workflow remains the stable cross-platform baseline.
+
+True vector clipboard copy and direct browser-to-PowerPoint drag are not part of this Experimental release. The `Copy SVG source` action copies SVG markup text; it is not a vector-image clipboard operation.
+
 ## Official Azure icons
 
 Download the current package from [Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/icons/) and use the icons in accordance with Microsoft's terms.

package/cli/powerpoint-bridge.js

@@ -0,0 +1,406 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export const POWERPOINT_CAPABILITY_PATH = "/__bridge/powerpoint/capability";
+export const POWERPOINT_COPY_ALL_PATH = "/__bridge/powerpoint/copy-all";
+export const POWERPOINT_CAPABILITY_HEADER = "x-cloud-arch-capability";
+export const MAX_POWERPOINT_OBJECTS = 36;
+const MAX_UNIQUE_IMAGES = 36;
+const MAX_IMAGE_BYTES = 2 * 1024 * 1024;
+const MAX_REQUEST_BYTES = 12 * 1024 * 1024;
+const POWERPOINT_TIMEOUT_MS = 20_000;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+class PowerPointAutomationError extends Error {
+    kind;
+    constructor(message, kind) {
+        super(message);
+        this.kind = kind;
+        this.name = "PowerPointAutomationError";
+    }
+}
+export function createPowerPointBridge(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const capabilityToken = options.capabilityToken ?? randomBytes(32).toString("base64url");
+    const runner = options.runner ?? runPowerPointCopy;
+    let busy = false;
+    return {
+        matches: (rawUrl) => {
+            const pathname = requestPathname(rawUrl);
+            return (pathname === POWERPOINT_CAPABILITY_PATH ||
+                pathname === POWERPOINT_COPY_ALL_PATH);
+        },
+        handle: async (request, response, port) => {
+            const pathname = requestPathname(request.url);
+            if (pathname === POWERPOINT_CAPABILITY_PATH) {
+                if (request.method !== "GET") {
+                    response.setHeader("Allow", "GET");
+                    sendJson(response, 405, { error: "Method Not Allowed" });
+                    return;
+                }
+                const available = platform === "win32";
+                sendJson(response, 200, {
+                    available,
+                    experimental: true,
+                    maxObjects: MAX_POWERPOINT_OBJECTS,
+                    capability: available ? capabilityToken : null,
+                    reason: available ? null : "windows-npx-only",
+                });
+                return;
+            }
+            if (pathname !== POWERPOINT_COPY_ALL_PATH) {
+                sendJson(response, 404, { error: "Not Found" });
+                return;
+            }
+            if (request.method !== "POST") {
+                response.setHeader("Allow", "POST");
+                sendJson(response, 405, { error: "Method Not Allowed" });
+                return;
+            }
+            if (platform !== "win32") {
+                sendJson(response, 501, {
+                    error: "PowerPoint Copy all is available only in the Windows npx runtime.",
+                });
+                return;
+            }
+            const expectedOrigin = `http://127.0.0.1:${port}`;
+            if (request.headers.origin !== expectedOrigin) {
+                sendJson(response, 403, { error: "Forbidden" });
+                return;
+            }
+            if (request.headers[POWERPOINT_CAPABILITY_HEADER] !== capabilityToken) {
+                sendJson(response, 403, { error: "Forbidden" });
+                return;
+            }
+            if (!isJsonContentType(request.headers["content-type"])) {
+                sendJson(response, 415, { error: "Expected application/json." });
+                return;
+            }
+            if (busy) {
+                sendJson(response, 409, {
+                    error: "A PowerPoint copy operation is already in progress.",
+                });
+                return;
+            }
+            let items;
+            try {
+                const raw = await readBoundedBody(request);
+                items = parseCopyPayload(JSON.parse(raw));
+            }
+            catch (error) {
+                if (error instanceof RequestTooLargeError) {
+                    sendJson(response, 413, { error: error.message });
+                    return;
+                }
+                sendJson(response, 400, {
+                    error: error instanceof Error ? error.message : "Invalid Copy all payload.",
+                });
+                return;
+            }
+            busy = true;
+            try {
+                await runner(items);
+                sendJson(response, 200, {
+                    ok: true,
+                    objectCount: items.reduce((sum, item) => sum + item.quantity, 0),
+                });
+            }
+            catch (error) {
+                const message = error instanceof PowerPointAutomationError
+                    ? error.message
+                    : "PowerPoint automation failed. Try again with desktop PowerPoint available.";
+                sendJson(response, 503, { error: message });
+            }
+            finally {
+                busy = false;
+            }
+        },
+    };
+}
+export function parseCopyPayload(value) {
+    if (!isRecord(value) || !Array.isArray(value.items)) {
+        throw new Error("Copy all payload must contain an items array.");
+    }
+    if (value.items.length === 0 || value.items.length > MAX_UNIQUE_IMAGES) {
+        throw new Error(`Copy all supports 1-${MAX_UNIQUE_IMAGES} unique images.`);
+    }
+    let total = 0;
+    const parsed = [];
+    for (const item of value.items) {
+        if (!isRecord(item))
+            throw new Error("Each Copy all item must be an object.");
+        const keys = Object.keys(item).sort();
+        if (keys.length !== 2 || keys[0] !== "pngBase64" || keys[1] !== "quantity") {
+            throw new Error("Copy all items may contain only pngBase64 and quantity.");
+        }
+        if (typeof item.quantity !== "number" ||
+            !Number.isSafeInteger(item.quantity) ||
+            item.quantity < 1 ||
+            item.quantity > MAX_POWERPOINT_OBJECTS) {
+            throw new Error("Copy all item quantity is invalid.");
+        }
+        if (typeof item.pngBase64 !== "string") {
+            throw new Error("Copy all image must be base64 PNG data.");
+        }
+        const png = decodePng(item.pngBase64);
+        total += item.quantity;
+        if (total > MAX_POWERPOINT_OBJECTS) {
+            throw new Error(`Copy all supports at most ${MAX_POWERPOINT_OBJECTS} objects.`);
+        }
+        parsed.push({ png, quantity: item.quantity });
+    }
+    return parsed;
+}
+async function runPowerPointCopy(items) {
+    const directory = await mkdtemp(join(tmpdir(), "cloud-arch-icon-browser-powerpoint-"));
+    try {
+        const manifestItems = [];
+        for (let index = 0; index < items.length; index += 1) {
+            const item = items[index];
+            if (item === undefined)
+                continue;
+            const path = join(directory, `${String(index).padStart(2, "0")}.png`);
+            await writeFile(path, item.png, { flag: "wx" });
+            manifestItems.push({ path, quantity: item.quantity });
+        }
+        const manifestPath = join(directory, "manifest.json");
+        await writeFile(manifestPath, JSON.stringify({
+            total: items.reduce((sum, item) => sum + item.quantity, 0),
+            items: manifestItems,
+        }), { encoding: "utf8", flag: "wx" });
+        await invokePowerPointAutomation(manifestPath);
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+function invokePowerPointAutomation(manifestPath) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const encodedCommand = Buffer.from(POWERPOINT_COPY_SCRIPT, "utf16le").toString("base64");
+        const child = spawn("powershell.exe", [
+            "-NoLogo",
+            "-NoProfile",
+            "-NonInteractive",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-EncodedCommand",
+            encodedCommand,
+        ], {
+            windowsHide: true,
+            stdio: ["ignore", "ignore", "pipe"],
+            env: { ...process.env, CAB_POWERPOINT_MANIFEST: manifestPath },
+        });
+        let stderr = "";
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (error)
+                rejectPromise(error);
+            else
+                resolvePromise();
+        };
+        child.stderr.on("data", (chunk) => {
+            stderr = `${stderr}${chunk.toString("utf8")}`.slice(-8192);
+        });
+        child.once("error", (error) => {
+            if ("code" in error && error.code === "ENOENT") {
+                finish(new PowerPointAutomationError("Windows PowerShell is unavailable, so PowerPoint Copy all cannot run.", "not-installed"));
+                return;
+            }
+            finish(new PowerPointAutomationError("PowerPoint automation could not be started.", "automation-failed"));
+        });
+        child.once("close", (code) => {
+            if (code === 0) {
+                finish();
+                return;
+            }
+            if (stderr.includes("CAB_POWERPOINT_NOT_INSTALLED")) {
+                finish(new PowerPointAutomationError("Desktop Microsoft PowerPoint was not found. Install/open desktop PowerPoint and try again.", "not-installed"));
+                return;
+            }
+            finish(new PowerPointAutomationError("PowerPoint could not prepare the multi-object clipboard. Close modal dialogs in PowerPoint and try again.", "automation-failed"));
+        });
+        const timeout = setTimeout(() => {
+            child.kill();
+            finish(new PowerPointAutomationError("PowerPoint Copy all timed out. Close PowerPoint dialogs and try again.", "timeout"));
+        }, POWERPOINT_TIMEOUT_MS);
+        timeout.unref();
+    });
+}
+function decodePng(base64) {
+    if (base64.length === 0 ||
+        base64.length % 4 !== 0 ||
+        !/^[A-Za-z0-9+/]*={0,2}$/.test(base64)) {
+        throw new Error("Copy all image contains invalid base64 data.");
+    }
+    const png = Buffer.from(base64, "base64");
+    if (png.length === 0 || png.length > MAX_IMAGE_BYTES) {
+        throw new Error("Copy all PNG size is outside the allowed range.");
+    }
+    if (png.length < PNG_SIGNATURE.length || !png.subarray(0, 8).equals(PNG_SIGNATURE)) {
+        throw new Error("Copy all accepts PNG images only.");
+    }
+    return png;
+}
+async function readBoundedBody(request) {
+    const declared = Number(request.headers["content-length"] ?? 0);
+    if (Number.isFinite(declared) && declared > MAX_REQUEST_BYTES) {
+        throw new RequestTooLargeError();
+    }
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.length;
+        if (total > MAX_REQUEST_BYTES)
+            throw new RequestTooLargeError();
+        chunks.push(buffer);
+    }
+    if (total === 0)
+        throw new Error("Copy all payload is empty.");
+    return Buffer.concat(chunks).toString("utf8");
+}
+class RequestTooLargeError extends Error {
+    constructor() {
+        super("Copy all payload is too large.");
+        this.name = "RequestTooLargeError";
+    }
+}
+function requestPathname(rawUrl) {
+    if (!rawUrl?.startsWith("/") || rawUrl.startsWith("//"))
+        return null;
+    const queryIndex = rawUrl.indexOf("?");
+    return queryIndex === -1 ? rawUrl : rawUrl.slice(0, queryIndex);
+}
+function isJsonContentType(value) {
+    return value?.toLowerCase().split(";", 1)[0]?.trim() === "application/json";
+}
+function sendJson(response, statusCode, value) {
+    const body = Buffer.from(JSON.stringify(value));
+    response.statusCode = statusCode;
+    response.setHeader("Content-Type", "application/json; charset=utf-8");
+    response.setHeader("Content-Length", String(body.length));
+    response.setHeader("Cache-Control", "no-store");
+    response.end(body);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const POWERPOINT_COPY_SCRIPT = String.raw `
+$ErrorActionPreference = "Stop"
+Set-StrictMode -Version Latest
+$MsoFalse = 0
+$MsoTrue = -1
+$PpLayoutBlank = 12
+$manifestPath = $env:CAB_POWERPOINT_MANIFEST
+$application = $null
+$presentation = $null
+$slide = $null
+$shapeRange = $null
+$ownedApplication = $false
+
+function Release-ComObject {
+  param($Object)
+  if ($null -ne $Object -and [Runtime.InteropServices.Marshal]::IsComObject($Object)) {
+    try { [void][Runtime.InteropServices.Marshal]::FinalReleaseComObject($Object) } catch {}
+  }
+}
+
+try {
+  if ([string]::IsNullOrWhiteSpace($manifestPath) -or -not (Test-Path -LiteralPath $manifestPath)) {
+    throw "Missing internal Copy all manifest."
+  }
+
+  try {
+    $application = [Runtime.InteropServices.Marshal]::GetActiveObject("PowerPoint.Application")
+  }
+  catch {
+    try {
+      $application = New-Object -ComObject PowerPoint.Application
+      $ownedApplication = $true
+    }
+    catch {
+      [Console]::Error.WriteLine("CAB_POWERPOINT_NOT_INSTALLED")
+      exit 21
+    }
+  }
+
+  $manifest = Get-Content -LiteralPath $manifestPath -Raw -Encoding UTF8 | ConvertFrom-Json
+  $presentation = $application.Presentations.Add($MsoFalse)
+  $slide = $presentation.Slides.Add(1, $PpLayoutBlank)
+  $shapeNames = New-Object System.Collections.Generic.List[object]
+  $columns = [Math]::Ceiling([Math]::Sqrt([double]$manifest.total))
+  $index = 0
+
+  foreach ($item in $manifest.items) {
+    for ($copy = 0; $copy -lt [int]$item.quantity; $copy++) {
+      $column = $index % $columns
+      $row = [Math]::Floor($index / $columns)
+      $left = 10 + ($column * 86)
+      $top = 10 + ($row * 86)
+      $shape = $slide.Shapes.AddPicture(
+        [string]$item.path,
+        $MsoFalse,
+        $MsoTrue,
+        [single]$left,
+        [single]$top,
+        [single]72,
+        [single]72
+      )
+      try {
+        $null = $shapeNames.Add([string]$shape.Name)
+      }
+      finally {
+        Release-ComObject $shape
+      }
+      $index++
+    }
+  }
+
+  $shapeRange = $slide.Shapes.Range([object[]]$shapeNames.ToArray())
+  $shapeRange.Copy()
+  Start-Sleep -Milliseconds 350
+  $presentation.Saved = $MsoTrue
+  $presentation.Close()
+  Release-ComObject $shapeRange
+  $shapeRange = $null
+  Release-ComObject $slide
+  $slide = $null
+  Release-ComObject $presentation
+  $presentation = $null
+
+  if ($ownedApplication) {
+    $application.Quit()
+  }
+  Release-ComObject $application
+  $application = $null
+  [GC]::Collect()
+  [GC]::WaitForPendingFinalizers()
+  exit 0
+}
+catch {
+  [Console]::Error.WriteLine("CAB_POWERPOINT_AUTOMATION_FAILED")
+  exit 22
+}
+finally {
+  if ($null -ne $shapeRange) { Release-ComObject $shapeRange }
+  if ($null -ne $slide) { Release-ComObject $slide }
+  if ($null -ne $presentation) {
+    try {
+      $presentation.Saved = $MsoTrue
+      $presentation.Close()
+    } catch {}
+    Release-ComObject $presentation
+  }
+  if ($null -ne $application) {
+    if ($ownedApplication) { try { $application.Quit() } catch {} }
+    Release-ComObject $application
+  }
+  [GC]::Collect()
+  [GC]::WaitForPendingFinalizers()
+}
+`;

package/cli/server.js

@@ -1,7 +1,12 @@
 import { readFile, readdir, realpath } from "node:fs/promises";
-import { createServer, } from "node:http";
+import { createServer, request as httpRequest, } from "node:http";
 import { extname, resolve, sep } from "node:path";
+import { createPowerPointBridge, } from "./powerpoint-bridge.js";
 const LOOPBACK_HOST = "127.0.0.1";
+export const CANONICAL_PORT = 41731;
+export const APP_INSTANCE_HEADER = "X-Cloud-Arch-Icon-Browser-Instance";
+const APP_INSTANCE_HEADER_VALUE = "1";
+const EXISTING_INSTANCE_PROBE_TIMEOUT_MS = 750;
 const CONTENT_SECURITY_POLICY = [
     "default-src 'self'",
     "script-src 'self'",
@@ -37,48 +42,69 @@ const MIME_TYPES = new Map([
 export async function startStaticServer(options) {
     const rootDirectory = await realpath(options.rootDirectory);
     const staticAssets = await loadStaticAssets(rootDirectory);
-    let selectedPort = 0;
+    const powerPointBridge = options.powerPointBridge ?? createPowerPointBridge();
+    const requestedPort = options.port ?? CANONICAL_PORT;
+    let selectedPort = requestedPort;
     const server = createServer((request, response) => {
-        try {
-            handleRequest(request, response, staticAssets, selectedPort);
-        }
-        catch {
+        void handleRequest(request, response, staticAssets, powerPointBridge, selectedPort).catch(() => {
             if (!response.headersSent) {
                 sendText(request, response, 500, "Internal Server Error\n");
                 return;
             }
             response.destroy();
-        }
+        });
     });
     server.on("clientError", (_error, socket) => {
         if (socket.writable) {
             socket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
         }
     });
-    await listenOnAvailablePort(server);
+    try {
+        await listenOnPort(server, requestedPort);
+    }
+    catch (error) {
+        if (requestedPort > 0 && isAddressInUseError(error)) {
+            const reused = await probeExistingInstance(requestedPort);
+            if (reused) {
+                return {
+                    port: requestedPort,
+                    url: appUrl(requestedPort),
+                    reused: true,
+                    close: () => Promise.resolve(),
+                };
+            }
+            throw new Error(`Port ${requestedPort} is already in use by another process. Stop that process and run cloud-arch-icon-browser again.`, { cause: error });
+        }
+        throw error;
+    }
     const address = server.address();
     if (address === null || typeof address === "string") {
         await closeServer(server);
         throw new Error("Unable to determine the localhost server port.");
     }
     selectedPort = address.port;
-    const url = `http://${LOOPBACK_HOST}:${selectedPort}/`;
+    const url = appUrl(selectedPort);
     let closePromise = null;
     return {
         port: selectedPort,
         url,
+        reused: false,
         close: () => {
             closePromise ??= closeServer(server);
             return closePromise;
         },
     };
 }
-function handleRequest(request, response, staticAssets, port) {
+async function handleRequest(request, response, staticAssets, powerPointBridge, port) {
     applySecurityHeaders(response);
     if (!isExpectedHost(request.headers.host, port)) {
         sendText(request, response, 403, "Forbidden\n");
         return;
     }
+    if (powerPointBridge.matches(request.url)) {
+        await powerPointBridge.handle(request, response, port);
+        return;
+    }
     if (request.method !== "GET" && request.method !== "HEAD") {
         response.setHeader("Allow", "GET, HEAD");
         sendText(request, response, 405, "Method Not Allowed\n");
@@ -192,6 +218,7 @@ function cacheControlFor(relativePath) {
     return "no-cache";
 }
 function applySecurityHeaders(response) {
+    response.setHeader(APP_INSTANCE_HEADER, APP_INSTANCE_HEADER_VALUE);
     response.setHeader("Content-Security-Policy", CONTENT_SECURITY_POLICY);
     response.setHeader("Cross-Origin-Opener-Policy", "same-origin");
     response.setHeader("Permissions-Policy", permissionsPolicy());
@@ -224,7 +251,7 @@ function sendText(request, response, statusCode, body) {
     }
     response.end(body);
 }
-function listenOnAvailablePort(server) {
+function listenOnPort(server, port) {
     return new Promise((resolvePromise, rejectPromise) => {
         const handleError = (error) => {
             server.off("listening", handleListening);
@@ -236,9 +263,45 @@ function listenOnAvailablePort(server) {
         };
         server.once("error", handleError);
         server.once("listening", handleListening);
-        server.listen({ host: LOOPBACK_HOST, port: 0 });
+        server.listen({ host: LOOPBACK_HOST, port });
     });
 }
+function probeExistingInstance(port) {
+    return new Promise((resolvePromise) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolvePromise(result);
+        };
+        const clientRequest = httpRequest({
+            host: LOOPBACK_HOST,
+            port,
+            path: "/",
+            method: "HEAD",
+            headers: { Host: `${LOOPBACK_HOST}:${port}` },
+        }, (response) => {
+            const header = response.headers[APP_INSTANCE_HEADER.toLowerCase()];
+            response.resume();
+            finish(header === APP_INSTANCE_HEADER_VALUE);
+        });
+        clientRequest.setTimeout(EXISTING_INSTANCE_PROBE_TIMEOUT_MS, () => {
+            clientRequest.destroy();
+            finish(false);
+        });
+        clientRequest.on("error", () => finish(false));
+        clientRequest.end();
+    });
+}
+function isAddressInUseError(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "EADDRINUSE");
+}
+function appUrl(port) {
+    return `http://${LOOPBACK_HOST}:${port}/`;
+}
 function closeServer(server) {
     if (!server.listening)
         return Promise.resolve();