@azphalt/web-handoff 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Az
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The web→host install handoff from `spec/web-handoff.md`, for any web storefront.
+ *
+ * The spec requires the same ladder of every conforming storefront — build the link, attempt it,
+ * detect that nothing claimed it, fall back to the `.azp` download and the host directory — and the
+ * middle step is a **heuristic**, because no browser API answers "is this scheme registered". A
+ * heuristic reimplemented per storefront is a heuristic that behaves differently per storefront, so
+ * it lives here once instead.
+ *
+ * The Compose storefront's `models/InstallHandoff.kt` + `network/WasmHandoff.kt` are the Kotlin
+ * counterpart, deliberately making the same decisions in the same order. Two storefronts that
+ * disagree about what pressing Install does would be two products wearing one name.
+ */
+/**
+ * The minimum a package must look like for this module to act on it.
+ *
+ * Structural rather than an import of `@azphalt/azdk`'s `PackageSummary` on purpose: a storefront may
+ * carry its own catalogue type (the React storefront does), and forcing every consumer onto one
+ * nominal type would make this package harder to adopt than reimplementing it — which is the outcome
+ * it exists to prevent. Anything with these fields satisfies it.
+ */
+export interface HandoffPackage {
+    id: string;
+    name: string;
+    version: string;
+    /** Reverse-DNS host ids this package is scoped to. Empty/absent = global. */
+    targetApps?: string[];
+    /** The reduced `app` block from a `kind:"app"` summary (`spec/repository-api.md` § The `app` summary). */
+    app?: {
+        roles?: string[];
+        hostId?: string;
+        platforms?: {
+            android?: {
+                install?: string;
+            };
+            pwa?: {
+                startUrl?: string;
+            };
+        };
+    };
+}
+/**
+ * The link a storefront emits for a package.
+ *
+ * Host-agnostic by construction (`web-handoff.md` § Why a custom scheme): no host is named, so any
+ * conforming host may claim it and the OS disambiguates when several do. A pack uses this same shape —
+ * it is a package with an id, and the host resolves its members.
+ */
+export declare function installLink(id: string, version?: string, repo?: string): string;
+/** A host worth offering to someone who has none installed. */
+export interface HostOption {
+    name: string;
+    hostId: string;
+    installUrl: string;
+}
+/**
+ * The hosts from `catalog` that could run `pkg`, for the "get a host" half of the fallback.
+ *
+ * An app-scoped package (`targetApps` non-empty) offers only the hosts it names — pitching a
+ * Guillotine-only pack at a paint app wastes the user's time in the one place they are already stuck.
+ * A listing with no install URL is dropped rather than shown as a dead entry.
+ */
+export declare function hostsFor(pkg: HandoffPackage, catalog: HandoffPackage[]): HostOption[];
+/**
+ * The conforming download URL — the `.azp` half of the fallback, which works with no link support at
+ * all because a host registered for the media type opens the downloaded file directly.
+ *
+ * Relative on purpose: a conforming storefront serving this bundle from its own domain should hand
+ * out its own bytes, not the flagship registry's.
+ */
+export declare function downloadUrl(id: string, version: string): string;
+/**
+ * Fire the link and report whether anything took it.
+ *
+ * `true` means a host claimed it and the user has left. `false` means nothing did, and the caller
+ * should show the fallback (`web-handoff.md` § When no host is installed).
+ *
+ * The attempt is made unconditionally — there is no "is a host likely on this platform" check first,
+ * because any such check is a list of platforms someone thought hosts existed on, and it fails closed
+ * against exactly the hosts it has not heard of yet.
+ *
+ * Departure is recorded by listeners rather than sampled at the end: a user can leave for a host and
+ * return well inside the wait window, and by then `visibilityState` is "visible" again. Sampling
+ * would read that as "nothing claimed it" and show the fallback to somebody who just installed.
+ */
+export declare function attemptHandoff(link: string): Promise<boolean>;

package/dist/index.js

@@ -0,0 +1,115 @@
+/** How long to wait before concluding nothing claimed the link. See `attemptHandoff`. */
+const HANDOFF_WAIT_MS = 1_400;
+/**
+ * The link a storefront emits for a package.
+ *
+ * Host-agnostic by construction (`web-handoff.md` § Why a custom scheme): no host is named, so any
+ * conforming host may claim it and the OS disambiguates when several do. A pack uses this same shape —
+ * it is a package with an id, and the host resolves its members.
+ */
+export function installLink(id, version, repo) {
+    const params = new URLSearchParams();
+    params.set("id", id);
+    // Always sent when known: the storefront is displaying the version, so making the host re-resolve
+    // `latest` would be a round-trip to learn what we already had.
+    if (version?.trim())
+        params.set("version", version);
+    if (repo?.trim())
+        params.set("repo", repo);
+    // URLSearchParams form-encodes, which writes a space as '+'. A strict RFC 3986 parser reads '+' as
+    // a literal plus, so the id would arrive at the host altered.
+    return `azphalt://install?${params.toString().replace(/\+/g, "%20")}`;
+}
+/**
+ * The hosts from `catalog` that could run `pkg`, for the "get a host" half of the fallback.
+ *
+ * An app-scoped package (`targetApps` non-empty) offers only the hosts it names — pitching a
+ * Guillotine-only pack at a paint app wastes the user's time in the one place they are already stuck.
+ * A listing with no install URL is dropped rather than shown as a dead entry.
+ */
+export function hostsFor(pkg, catalog) {
+    const wanted = new Set(pkg.targetApps ?? []);
+    const out = [];
+    const seen = new Set();
+    for (const candidate of catalog) {
+        const app = candidate.app;
+        if (!app)
+            continue;
+        // Absent `roles` means `["companion"]`; the API resolves that before serving, but a storefront
+        // pointed at an older deployment should not start offering companions as hosts.
+        if (!(app.roles ?? ["companion"]).includes("host"))
+            continue;
+        if (!app.hostId)
+            continue;
+        if (wanted.size > 0 && !wanted.has(app.hostId))
+            continue;
+        const installUrl = app.platforms?.android?.install ?? app.platforms?.pwa?.startUrl;
+        if (!installUrl)
+            continue;
+        if (seen.has(app.hostId))
+            continue;
+        seen.add(app.hostId);
+        out.push({ name: candidate.name, hostId: app.hostId, installUrl });
+    }
+    return out;
+}
+/**
+ * The conforming download URL — the `.azp` half of the fallback, which works with no link support at
+ * all because a host registered for the media type opens the downloaded file directly.
+ *
+ * Relative on purpose: a conforming storefront serving this bundle from its own domain should hand
+ * out its own bytes, not the flagship registry's.
+ */
+export function downloadUrl(id, version) {
+    return `/packages/${encodeURIComponent(id)}/versions/${encodeURIComponent(version)}/download`;
+}
+/**
+ * Fire the link and report whether anything took it.
+ *
+ * `true` means a host claimed it and the user has left. `false` means nothing did, and the caller
+ * should show the fallback (`web-handoff.md` § When no host is installed).
+ *
+ * The attempt is made unconditionally — there is no "is a host likely on this platform" check first,
+ * because any such check is a list of platforms someone thought hosts existed on, and it fails closed
+ * against exactly the hosts it has not heard of yet.
+ *
+ * Departure is recorded by listeners rather than sampled at the end: a user can leave for a host and
+ * return well inside the wait window, and by then `visibilityState` is "visible" again. Sampling
+ * would read that as "nothing claimed it" and show the fallback to somebody who just installed.
+ */
+export function attemptHandoff(link) {
+    return new Promise((resolve) => {
+        let left = false;
+        const mark = () => {
+            left = true;
+        };
+        const onVisibility = () => {
+            if (document.visibilityState !== "visible")
+                left = true;
+        };
+        window.addEventListener("pagehide", mark);
+        window.addEventListener("blur", mark);
+        document.addEventListener("visibilitychange", onVisibility);
+        const cleanup = () => {
+            window.removeEventListener("pagehide", mark);
+            window.removeEventListener("blur", mark);
+            document.removeEventListener("visibilitychange", onVisibility);
+        };
+        try {
+            // `location.href` rather than an iframe: modern browsers treat a top-level navigation to an
+            // unhandled scheme as a no-op, which is the behaviour this whole dance is built around. An
+            // iframe would be blocked outright in several of them.
+            window.location.href = link;
+        }
+        catch {
+            // A navigation the browser refuses is "no host", not an error to surface.
+            cleanup();
+            resolve(false);
+            return;
+        }
+        window.setTimeout(() => {
+            cleanup();
+            resolve(left);
+        }, HANDOFF_WAIT_MS);
+    });
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@azphalt/web-handoff",
+  "version": "0.2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "The web→host install handoff from spec/web-handoff.md — build the azphalt://install link, attempt it, and fall back when no host claims it.",
+  "license": "MIT",
+  "author": "Az (https://hereliesaz.com)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  }
+}