@flighthq/protocol 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './protocol';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './protocol';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,22 @@
+import type { ParsedProtocolUrl, ProtocolBackend, ProtocolHandler } from '@flighthq/types';
+export declare function attachProtocolHandler(handler: ProtocolHandler): void;
+export declare function createProtocolHandler(): ProtocolHandler;
+export declare function createProtocolUrl(parts: Readonly<Partial<ParsedProtocolUrl>>): string;
+export declare function createWebProtocolBackend(): ProtocolBackend;
+export declare function detachProtocolHandler(handler: ProtocolHandler): void;
+export declare function disposeProtocolHandler(handler: ProtocolHandler): void;
+export declare function getProtocolBackend(): ProtocolBackend;
+export declare function getProtocolLaunchUrl(): string | null;
+export declare function getRegisteredProtocolSchemes(): readonly string[];
+export declare function isProtocolSchemeDefault(scheme: string): boolean;
+export declare function isProtocolSchemeRegistered(scheme: string): boolean;
+export declare function isValidProtocolScheme(scheme: string): boolean;
+export declare function parseProtocolUrl(url: string): ParsedProtocolUrl | null;
+export declare function registerProtocolScheme(scheme: string): boolean;
+export declare function registerProtocolSchemes(schemes: readonly string[]): boolean;
+export declare function removeProtocolSchemeAsDefault(scheme: string): boolean;
+export declare function setProtocolBackend(backend: ProtocolBackend | null): void;
+export declare function setProtocolSchemeAsDefault(scheme: string): boolean;
+export declare function unregisterProtocolScheme(scheme: string): boolean;
+export declare function unregisterProtocolSchemes(schemes: readonly string[]): boolean;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAO3F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAUpE;AAID,wBAAgB,qBAAqB,IAAI,eAAe,CAEvD;AAKD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAgBrF;AAID,wBAAgB,wBAAwB,IAAI,eAAe,CAiE1D;AAGD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAMpE;AAID,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAErE;AAGD,wBAAgB,kBAAkB,IAAI,eAAe,CAGpD;AAKD,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,IAAI,CAEpD;AAID,wBAAgB,4BAA4B,IAAI,SAAS,MAAM,EAAE,CAEhE;AAID,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE/D;AAGD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAElE;AAMD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAK7D;AAMD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAuDtE;AAKD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAG9D;AAID,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAO3E;AAID,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErE;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAExE;AAID,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAElE;AAID,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEhE;AAGD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAO7E"}

package/dist/protocol.js

@@ -0,0 +1,293 @@
+import { createSignal, emitSignal } from '@flighthq/signals';
+// Begins delivering deep-link opens to `handler`'s signal by subscribing to the active backend. Wires
+// subscribe→onOpenUrl. Idempotent: a prior subscription is torn down first. Drains any URLs that
+// arrived before this call (buffered by the backend between process start and first attach) and
+// emits each one before activating the live subscription. Pair with
+// detachProtocolHandler/disposeProtocolHandler.
+export function attachProtocolHandler(handler) {
+    detachProtocolHandler(handler);
+    const backend = getProtocolBackend();
+    // Drain URLs that arrived between process start and first attach (pre-attach burst).
+    const pending = backend.drainPendingUrls();
+    for (const url of pending) {
+        emitSignal(handler.onOpenUrl, url);
+    }
+    const unsubscribe = backend.subscribe((url) => emitSignal(handler.onOpenUrl, url));
+    _subscriptions.set(handler, unsubscribe);
+}
+// Allocates a ProtocolHandler event entity with an inert signal; call attachProtocolHandler to start
+// delivery.
+export function createProtocolHandler() {
+    return { onOpenUrl: createSignal() };
+}
+// Builds a protocol URL string from its parsed components. scheme, host, path, and query are all
+// optional; the result is always a valid absolute URI string. Round-trips with parseProtocolUrl for
+// well-formed inputs.
+export function createProtocolUrl(parts) {
+    const scheme = parts.scheme ?? 'unknown';
+    const host = parts.host ?? '';
+    const path = parts.path ?? '';
+    const query = parts.query;
+    const authority = host ? `//${host}` : '';
+    const normalizedPath = path && !path.startsWith('/') ? `/${path}` : path;
+    let url = `${scheme}:${authority}${normalizedPath}`;
+    if (query) {
+        const entries = Object.entries(query).filter(([k]) => k.length > 0);
+        if (entries.length > 0) {
+            const qs = entries.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&');
+            url += `?${qs}`;
+        }
+    }
+    return url;
+}
+// Builds the default web backend over navigator.registerProtocolHandler. Registration degrades to
+// false where the API is absent. Deep-link delivery needs a native host, so subscribe is inert.
+export function createWebProtocolBackend() {
+    const _registeredSchemes = [];
+    return {
+        register(scheme) {
+            if (typeof navigator === 'undefined' || typeof location === 'undefined')
+                return false;
+            const nav = navigator;
+            if (typeof nav.registerProtocolHandler !== 'function')
+                return false;
+            try {
+                nav.registerProtocolHandler(scheme, location.origin + '/?url=%s');
+                if (!_registeredSchemes.includes(scheme))
+                    _registeredSchemes.push(scheme);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        unregister(scheme) {
+            // The web platform offers no programmatic unregister; report failure rather than throw.
+            const idx = _registeredSchemes.indexOf(scheme);
+            if (idx >= 0)
+                _registeredSchemes.splice(idx, 1);
+            return false;
+        },
+        isRegistered() {
+            // The web platform offers no registration query; report not-registered.
+            return false;
+        },
+        getRegisteredSchemes() {
+            // Web cannot enumerate registered schemes reliably; return what we tracked locally.
+            return _registeredSchemes.slice();
+        },
+        setAsDefault() {
+            // The web platform cannot claim a scheme as the OS default; report failure.
+            return false;
+        },
+        isDefault() {
+            // The web platform cannot query OS default handler; report false.
+            return false;
+        },
+        removeAsDefault() {
+            // The web platform cannot remove an OS default handler; report failure.
+            return false;
+        },
+        getLaunchUrl() {
+            // On the web the registered handler redirects to /?url=<encoded-url>. Read that query param as
+            // the cold-start launch URL when present.
+            if (typeof location === 'undefined')
+                return null;
+            try {
+                const params = new URLSearchParams(location.search);
+                const url = params.get('url');
+                return url && url.length > 0 ? url : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        drainPendingUrls() {
+            // The web backend has no pre-attach buffering; the cold-start URL is handled by getLaunchUrl.
+            return [];
+        },
+        subscribe() {
+            // Web deep-link delivery requires a native host to route incoming URLs into the page; the web
+            // backend cannot observe protocol opens on its own, so this subscription is inert.
+            return () => { };
+        },
+    };
+}
+// Stops delivery to `handler` and forgets its subscription. Safe to call when not attached.
+export function detachProtocolHandler(handler) {
+    const unsubscribe = _subscriptions.get(handler);
+    if (unsubscribe !== undefined) {
+        unsubscribe();
+        _subscriptions.delete(handler);
+    }
+}
+// Releases `handler` for garbage collection by detaching its backend subscription. The signal remains
+// plain GC-managed memory afterward.
+export function disposeProtocolHandler(handler) {
+    detachProtocolHandler(handler);
+}
+// The active protocol backend, or a lazily-created web default. There is always a backend.
+export function getProtocolBackend() {
+    if (_backend === null)
+        _backend = createWebProtocolBackend();
+    return _backend;
+}
+// Returns the URL the app was launched with via a deep link (cold start), or null when the app was
+// not launched via a link. This is a one-shot idempotent query — re-readable. Distinct from
+// onOpenUrl, which fires only for warm (subsequent) opens.
+export function getProtocolLaunchUrl() {
+    return getProtocolBackend().getLaunchUrl();
+}
+// Returns all custom URI schemes currently registered by this app. Returns [] when the host cannot
+// enumerate registered schemes.
+export function getRegisteredProtocolSchemes() {
+    return getProtocolBackend().getRegisteredSchemes();
+}
+// True when `scheme` is the OS default handler for deep links. Returns false where the host cannot
+// report it (e.g. the web platform).
+export function isProtocolSchemeDefault(scheme) {
+    return getProtocolBackend().isDefault(scheme);
+}
+// True when `scheme` is currently registered to this app. Returns false where the host cannot report it.
+export function isProtocolSchemeRegistered(scheme) {
+    return getProtocolBackend().isRegistered(scheme);
+}
+// Returns true when `scheme` is a valid RFC 3986 URI scheme: starts with an ASCII letter followed by
+// zero or more letters, digits, '+', '-', or '.'. Reserved schemes ('http', 'https', 'ftp', 'ftps',
+// 'mailto', 'file') are rejected to prevent OS conflicts. Scheme is lowercased before validation so
+// 'MyApp' is treated identically to 'myapp'.
+export function isValidProtocolScheme(scheme) {
+    if (typeof scheme !== 'string' || scheme.length === 0)
+        return false;
+    const lower = scheme.toLowerCase();
+    if (_reservedSchemes.has(lower))
+        return false;
+    return _schemePattern.test(lower);
+}
+// Parses a deep-link URL into its components. Returns null for malformed or non-custom-scheme URLs.
+// query values are percent-decoded. Multi-value query keys: last value wins (matches URLSearchParams
+// behavior). This function does not allocate a large object on the happy path — it reads all fields
+// before writing to avoid aliasing issues if the caller reuses a buffer.
+export function parseProtocolUrl(url) {
+    if (typeof url !== 'string' || url.length === 0)
+        return null;
+    const colonIdx = url.indexOf(':');
+    if (colonIdx <= 0)
+        return null;
+    const scheme = url.slice(0, colonIdx).toLowerCase();
+    if (!_schemePattern.test(scheme))
+        return null;
+    let rest = url.slice(colonIdx + 1);
+    // Authority (//host)
+    let host = '';
+    if (rest.startsWith('//')) {
+        rest = rest.slice(2);
+        const slashIdx = rest.indexOf('/');
+        const qIdx = rest.indexOf('?');
+        let hostEnd;
+        if (slashIdx >= 0 && (qIdx < 0 || slashIdx < qIdx)) {
+            hostEnd = slashIdx;
+        }
+        else if (qIdx >= 0) {
+            hostEnd = qIdx;
+        }
+        else {
+            hostEnd = rest.length;
+        }
+        host = rest.slice(0, hostEnd);
+        rest = rest.slice(hostEnd);
+    }
+    // Path and query
+    const qIdx = rest.indexOf('?');
+    let path;
+    let queryString;
+    if (qIdx >= 0) {
+        path = rest.slice(0, qIdx);
+        queryString = rest.slice(qIdx + 1);
+    }
+    else {
+        path = rest;
+        queryString = '';
+    }
+    // Decode query
+    const query = {};
+    if (queryString.length > 0) {
+        for (const pair of queryString.split('&')) {
+            const eqIdx = pair.indexOf('=');
+            if (eqIdx < 0) {
+                const k = _safeDecode(pair);
+                if (k.length > 0)
+                    query[k] = '';
+            }
+            else {
+                const k = _safeDecode(pair.slice(0, eqIdx));
+                if (k.length > 0)
+                    query[k] = _safeDecode(pair.slice(eqIdx + 1));
+            }
+        }
+    }
+    return { scheme, host, path, query };
+}
+// Registers a custom URI scheme (for example 'myapp') to this app. Returns false when the scheme is
+// invalid (RFC 3986 grammar, no reserved schemes) or when the host denies or does not support
+// registration.
+export function registerProtocolScheme(scheme) {
+    if (!isValidProtocolScheme(scheme))
+        return false;
+    return getProtocolBackend().register(scheme);
+}
+// Registers multiple custom URI schemes in one call. Returns false if any scheme is invalid or if any
+// registration fails.
+export function registerProtocolSchemes(schemes) {
+    const backend = getProtocolBackend();
+    let allOk = true;
+    for (const scheme of schemes) {
+        if (!isValidProtocolScheme(scheme) || !backend.register(scheme))
+            allOk = false;
+    }
+    return allOk;
+}
+// Removes this app as the OS default handler for `scheme`. Returns false when the host denies or does
+// not support it.
+export function removeProtocolSchemeAsDefault(scheme) {
+    return getProtocolBackend().removeAsDefault(scheme);
+}
+// Installs a native host protocol backend; pass null to fall back to the web default.
+export function setProtocolBackend(backend) {
+    _backend = backend;
+}
+// Makes this app the default handler for `scheme`. Returns false when the host denies or does not
+// support it.
+export function setProtocolSchemeAsDefault(scheme) {
+    return getProtocolBackend().setAsDefault(scheme);
+}
+// Unregisters a previously registered custom URI scheme. Returns false when the host denies or does
+// not support unregistration.
+export function unregisterProtocolScheme(scheme) {
+    return getProtocolBackend().unregister(scheme);
+}
+// Unregisters multiple custom URI schemes in one call. Returns false if any unregistration fails.
+export function unregisterProtocolSchemes(schemes) {
+    const backend = getProtocolBackend();
+    let allOk = true;
+    for (const scheme of schemes) {
+        if (!backend.unregister(scheme))
+            allOk = false;
+    }
+    return allOk;
+}
+// RFC 3986 scheme grammar: letter followed by zero or more letter/digit/+/-/. (lowercased).
+const _schemePattern = /^[a-z][a-z0-9+\-.]*$/;
+// Schemes that should never be claimed as custom URI handlers to avoid OS conflicts.
+const _reservedSchemes = new Set(['file', 'ftp', 'ftps', 'http', 'https', 'mailto']);
+let _backend = null;
+const _subscriptions = new WeakMap();
+function _safeDecode(s) {
+    try {
+        return decodeURIComponent(s.replace(/\+/g, ' '));
+    }
+    catch {
+        return s;
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/protocol",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/signals": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Custom URI scheme registration and deep-link open-URL signals over a swappable web/native backend",
+  "sideEffects": false
+}

package/src/protocol.test.ts

@@ -0,0 +1,492 @@
+import { connectSignal } from '@flighthq/signals';
+import type { ProtocolBackend } from '@flighthq/types';
+
+import {
+  attachProtocolHandler,
+  createProtocolHandler,
+  createProtocolUrl,
+  createWebProtocolBackend,
+  detachProtocolHandler,
+  disposeProtocolHandler,
+  getProtocolBackend,
+  getProtocolLaunchUrl,
+  getRegisteredProtocolSchemes,
+  isProtocolSchemeDefault,
+  isProtocolSchemeRegistered,
+  isValidProtocolScheme,
+  parseProtocolUrl,
+  registerProtocolScheme,
+  registerProtocolSchemes,
+  removeProtocolSchemeAsDefault,
+  setProtocolBackend,
+  setProtocolSchemeAsDefault,
+  unregisterProtocolScheme,
+  unregisterProtocolSchemes,
+} from './protocol';
+
+function fakeBackend(): ProtocolBackend & {
+  registered: boolean;
+  defaulted: boolean;
+  launchUrl: string | null;
+  pendingUrls: string[];
+  fire: (url: string) => void;
+} {
+  let listener: ((url: string) => void) | null = null;
+  const registeredSchemes: string[] = [];
+  return {
+    registered: false,
+    defaulted: false,
+    launchUrl: null,
+    pendingUrls: [],
+    register(_scheme) {
+      this.registered = true;
+      if (!registeredSchemes.includes(_scheme)) registeredSchemes.push(_scheme);
+      return true;
+    },
+    unregister(_scheme) {
+      this.registered = false;
+      const idx = registeredSchemes.indexOf(_scheme);
+      if (idx >= 0) registeredSchemes.splice(idx, 1);
+      return true;
+    },
+    isRegistered(_scheme) {
+      return this.registered;
+    },
+    getRegisteredSchemes() {
+      return registeredSchemes.slice();
+    },
+    setAsDefault(_scheme) {
+      this.defaulted = true;
+      return true;
+    },
+    isDefault(_scheme) {
+      return this.defaulted;
+    },
+    removeAsDefault(_scheme) {
+      this.defaulted = false;
+      return true;
+    },
+    getLaunchUrl() {
+      return this.launchUrl;
+    },
+    drainPendingUrls() {
+      const drained = this.pendingUrls.slice();
+      this.pendingUrls = [];
+      return drained;
+    },
+    subscribe(l) {
+      listener = l;
+      return () => {
+        listener = null;
+      };
+    },
+    fire(url) {
+      listener?.(url);
+    },
+  };
+}
+
+afterEach(() => setProtocolBackend(null));
+
+describe('attachProtocolHandler', () => {
+  it('drains pre-attach pending URLs before subscribing', () => {
+    const backend = fakeBackend();
+    backend.pendingUrls = ['myapp://early/1', 'myapp://early/2'];
+    setProtocolBackend(backend);
+    const handler = createProtocolHandler();
+    const received: string[] = [];
+    connectSignal(handler.onOpenUrl, (url) => received.push(url));
+    attachProtocolHandler(handler);
+    expect(received).toEqual(['myapp://early/1', 'myapp://early/2']);
+    // Pending queue is cleared — a second attach does not re-deliver them.
+    attachProtocolHandler(handler);
+    expect(received).toEqual(['myapp://early/1', 'myapp://early/2']);
+  });
+
+  it('emits onOpenUrl when the backend delivers a deep link', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    const handler = createProtocolHandler();
+    let opened = '';
+    connectSignal(handler.onOpenUrl, (url) => (opened = url));
+    attachProtocolHandler(handler);
+    backend.fire('myapp://open/123');
+    expect(opened).toBe('myapp://open/123');
+  });
+
+  it('is idempotent — reattaching does not double-fire', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    const handler = createProtocolHandler();
+    let count = 0;
+    connectSignal(handler.onOpenUrl, () => count++);
+    attachProtocolHandler(handler);
+    attachProtocolHandler(handler);
+    backend.fire('myapp://x');
+    expect(count).toBe(1);
+  });
+});
+
+describe('createProtocolHandler', () => {
+  it('creates an entity with the open-URL signal', () => {
+    const handler = createProtocolHandler();
+    expect(handler.onOpenUrl).toBeDefined();
+  });
+});
+
+describe('createProtocolUrl', () => {
+  it('builds a basic URL from all parts', () => {
+    const url = createProtocolUrl({ scheme: 'myapp', host: 'open', path: '/item/1', query: { ref: 'home' } });
+    expect(url).toBe('myapp://open/item/1?ref=home');
+  });
+
+  it('omits authority when host is empty', () => {
+    const url = createProtocolUrl({ scheme: 'myapp', path: '/action' });
+    expect(url).toBe('myapp:/action');
+  });
+
+  it('omits query when no query params', () => {
+    const url = createProtocolUrl({ scheme: 'myapp', host: 'x' });
+    expect(url).toBe('myapp://x');
+  });
+
+  it('percent-encodes query keys and values', () => {
+    const url = createProtocolUrl({ scheme: 'myapp', query: { 'a b': 'c d' } });
+    expect(url).toContain('a%20b=c%20d');
+  });
+
+  it('round-trips with parseProtocolUrl', () => {
+    const parts = { scheme: 'myapp', host: 'host', path: '/path', query: { k: 'v' } };
+    const url = createProtocolUrl(parts);
+    const parsed = parseProtocolUrl(url);
+    expect(parsed?.scheme).toBe('myapp');
+    expect(parsed?.host).toBe('host');
+    expect(parsed?.path).toBe('/path');
+    expect(parsed?.query['k']).toBe('v');
+  });
+});
+
+describe('createWebProtocolBackend', () => {
+  it('reports a subscribe function and non-throwing queries', () => {
+    const backend = createWebProtocolBackend();
+    expect(backend.subscribe(() => {})).toBeInstanceOf(Function);
+    expect(typeof backend.isRegistered('myapp')).toBe('boolean');
+    expect(backend.setAsDefault('myapp')).toBe(false);
+    expect(backend.isDefault('myapp')).toBe(false);
+    expect(backend.removeAsDefault('myapp')).toBe(false);
+    expect(backend.getLaunchUrl()).toBeNull();
+    expect(backend.getRegisteredSchemes()).toBeInstanceOf(Array);
+  });
+});
+
+describe('detachProtocolHandler', () => {
+  it('stops further delivery', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    const handler = createProtocolHandler();
+    let opened = 0;
+    connectSignal(handler.onOpenUrl, () => opened++);
+    attachProtocolHandler(handler);
+    detachProtocolHandler(handler);
+    backend.fire('myapp://x');
+    expect(opened).toBe(0);
+  });
+
+  it('is safe when not attached', () => {
+    const handler = createProtocolHandler();
+    expect(() => detachProtocolHandler(handler)).not.toThrow();
+  });
+});
+
+describe('disposeProtocolHandler', () => {
+  it('detaches the subscription', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    const handler = createProtocolHandler();
+    attachProtocolHandler(handler);
+    expect(() => disposeProtocolHandler(handler)).not.toThrow();
+  });
+
+  it('stops delivery after dispose', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    const handler = createProtocolHandler();
+    let count = 0;
+    connectSignal(handler.onOpenUrl, () => count++);
+    attachProtocolHandler(handler);
+    disposeProtocolHandler(handler);
+    backend.fire('myapp://x');
+    expect(count).toBe(0);
+  });
+});
+
+describe('getProtocolBackend', () => {
+  it('falls back to a web backend', () => {
+    expect(getProtocolBackend()).not.toBeNull();
+  });
+
+  it('returns the installed backend', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    expect(getProtocolBackend()).toBe(backend);
+  });
+});
+
+describe('getProtocolLaunchUrl', () => {
+  it('returns null when no launch URL', () => {
+    const backend = fakeBackend();
+    backend.launchUrl = null;
+    setProtocolBackend(backend);
+    expect(getProtocolLaunchUrl()).toBeNull();
+  });
+
+  it('returns the launch URL when present', () => {
+    const backend = fakeBackend();
+    backend.launchUrl = 'myapp://cold-start/item';
+    setProtocolBackend(backend);
+    expect(getProtocolLaunchUrl()).toBe('myapp://cold-start/item');
+  });
+
+  it('is idempotent — returns the same value on repeated calls', () => {
+    const backend = fakeBackend();
+    backend.launchUrl = 'myapp://x';
+    setProtocolBackend(backend);
+    expect(getProtocolLaunchUrl()).toBe('myapp://x');
+    expect(getProtocolLaunchUrl()).toBe('myapp://x');
+  });
+});
+
+describe('getRegisteredProtocolSchemes', () => {
+  it('returns empty when no schemes registered', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    expect(getRegisteredProtocolSchemes()).toEqual([]);
+  });
+
+  it('includes schemes that have been registered', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    registerProtocolScheme('myapp');
+    expect(getRegisteredProtocolSchemes()).toContain('myapp');
+  });
+});
+
+describe('isProtocolSchemeDefault', () => {
+  it('returns false by default', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    expect(isProtocolSchemeDefault('myapp')).toBe(false);
+  });
+
+  it('returns true after setProtocolSchemeAsDefault', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    setProtocolSchemeAsDefault('myapp');
+    expect(isProtocolSchemeDefault('myapp')).toBe(true);
+  });
+
+  it('returns false after removeProtocolSchemeAsDefault', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    setProtocolSchemeAsDefault('myapp');
+    removeProtocolSchemeAsDefault('myapp');
+    expect(isProtocolSchemeDefault('myapp')).toBe(false);
+  });
+});
+
+describe('isProtocolSchemeRegistered', () => {
+  it('reflects the backend registration state', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    expect(isProtocolSchemeRegistered('myapp')).toBe(false);
+    registerProtocolScheme('myapp');
+    expect(isProtocolSchemeRegistered('myapp')).toBe(true);
+  });
+});
+
+describe('isValidProtocolScheme', () => {
+  it('accepts valid custom schemes', () => {
+    expect(isValidProtocolScheme('myapp')).toBe(true);
+    expect(isValidProtocolScheme('my-app')).toBe(true);
+    expect(isValidProtocolScheme('my.app')).toBe(true);
+    expect(isValidProtocolScheme('my+app')).toBe(true);
+    expect(isValidProtocolScheme('app123')).toBe(true);
+  });
+
+  it('rejects schemes not starting with a letter', () => {
+    expect(isValidProtocolScheme('1app')).toBe(false);
+    expect(isValidProtocolScheme('-app')).toBe(false);
+  });
+
+  it('rejects empty and non-string inputs', () => {
+    expect(isValidProtocolScheme('')).toBe(false);
+  });
+
+  it('rejects reserved schemes', () => {
+    expect(isValidProtocolScheme('http')).toBe(false);
+    expect(isValidProtocolScheme('https')).toBe(false);
+    expect(isValidProtocolScheme('ftp')).toBe(false);
+    expect(isValidProtocolScheme('mailto')).toBe(false);
+    expect(isValidProtocolScheme('file')).toBe(false);
+  });
+
+  it('is case-insensitive — lowercases before validation', () => {
+    expect(isValidProtocolScheme('MyApp')).toBe(true);
+    expect(isValidProtocolScheme('HTTP')).toBe(false);
+  });
+});
+
+describe('parseProtocolUrl', () => {
+  it('parses a full URL with host, path, and query', () => {
+    const result = parseProtocolUrl('myapp://host/path?foo=bar&baz=qux');
+    expect(result?.scheme).toBe('myapp');
+    expect(result?.host).toBe('host');
+    expect(result?.path).toBe('/path');
+    expect(result?.query['foo']).toBe('bar');
+    expect(result?.query['baz']).toBe('qux');
+  });
+
+  it('parses a URL with no host', () => {
+    const result = parseProtocolUrl('myapp:/action');
+    expect(result?.scheme).toBe('myapp');
+    expect(result?.host).toBe('');
+    expect(result?.path).toBe('/action');
+  });
+
+  it('parses a URL with no path', () => {
+    const result = parseProtocolUrl('myapp://host');
+    expect(result?.scheme).toBe('myapp');
+    expect(result?.host).toBe('host');
+    expect(result?.path).toBe('');
+  });
+
+  it('decodes percent-encoded query values', () => {
+    const result = parseProtocolUrl('myapp://x?key=hello%20world');
+    expect(result?.query['key']).toBe('hello world');
+  });
+
+  it('last-value-wins for duplicate query keys', () => {
+    const result = parseProtocolUrl('myapp://x?k=first&k=second');
+    expect(result?.query['k']).toBe('second');
+  });
+
+  it('returns null for malformed or empty input', () => {
+    expect(parseProtocolUrl('')).toBeNull();
+    expect(parseProtocolUrl('notaurl')).toBeNull();
+    expect(parseProtocolUrl(':noscheme')).toBeNull();
+  });
+
+  it('lowercases the scheme', () => {
+    const result = parseProtocolUrl('MyApp://host');
+    expect(result?.scheme).toBe('myapp');
+  });
+
+  it('handles URL with no query string', () => {
+    const result = parseProtocolUrl('myapp://host/path');
+    expect(result?.query).toEqual({});
+  });
+});
+
+describe('registerProtocolScheme', () => {
+  it('registers through the backend', () => {
+    setProtocolBackend(fakeBackend());
+    expect(registerProtocolScheme('myapp')).toBe(true);
+  });
+
+  it('returns false for an invalid scheme without calling the backend', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    expect(registerProtocolScheme('123invalid')).toBe(false);
+    expect(backend.registered).toBe(false);
+  });
+
+  it('returns false for a reserved scheme', () => {
+    setProtocolBackend(fakeBackend());
+    expect(registerProtocolScheme('https')).toBe(false);
+  });
+});
+
+describe('registerProtocolSchemes', () => {
+  it('registers multiple schemes and returns true when all succeed', () => {
+    setProtocolBackend(fakeBackend());
+    expect(registerProtocolSchemes(['myapp', 'myapp2'])).toBe(true);
+  });
+
+  it('returns false if any registration fails', () => {
+    const backend = fakeBackend();
+    let callCount = 0;
+    const orig = backend.register.bind(backend);
+    backend.register = (scheme) => {
+      callCount++;
+      return callCount === 1 ? orig(scheme) : false;
+    };
+    setProtocolBackend(backend);
+    expect(registerProtocolSchemes(['myapp', 'myapp2'])).toBe(false);
+  });
+
+  it('returns false and skips backend for invalid schemes in the batch', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    expect(registerProtocolSchemes(['myapp', 'http'])).toBe(false);
+    // 'myapp' succeeded but 'http' failed — registered reflects the partial success
+    expect(backend.registered).toBe(true);
+  });
+});
+
+describe('removeProtocolSchemeAsDefault', () => {
+  it('removes default status through the backend', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    setProtocolSchemeAsDefault('myapp');
+    expect(removeProtocolSchemeAsDefault('myapp')).toBe(true);
+    expect(isProtocolSchemeDefault('myapp')).toBe(false);
+  });
+});
+
+describe('setProtocolBackend', () => {
+  it('clears back to the web fallback when passed null', () => {
+    setProtocolBackend(fakeBackend());
+    setProtocolBackend(null);
+    expect(getProtocolBackend()).not.toBeNull();
+  });
+});
+
+describe('setProtocolSchemeAsDefault', () => {
+  it('marks the scheme as default through the backend', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    expect(setProtocolSchemeAsDefault('myapp')).toBe(true);
+    expect(backend.defaulted).toBe(true);
+  });
+});
+
+describe('unregisterProtocolScheme', () => {
+  it('unregisters through the backend', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    registerProtocolScheme('myapp');
+    expect(unregisterProtocolScheme('myapp')).toBe(true);
+    expect(backend.registered).toBe(false);
+  });
+});
+
+describe('unregisterProtocolSchemes', () => {
+  it('unregisters multiple schemes and returns true when all succeed', () => {
+    const backend = fakeBackend();
+    setProtocolBackend(backend);
+    registerProtocolScheme('myapp');
+    expect(unregisterProtocolSchemes(['myapp', 'myapp2'])).toBe(true);
+  });
+
+  it('returns false if any unregistration fails', () => {
+    const backend = fakeBackend();
+    let callCount = 0;
+    const orig = backend.unregister.bind(backend);
+    backend.unregister = (scheme) => {
+      callCount++;
+      return callCount === 1 ? orig(scheme) : false;
+    };
+    setProtocolBackend(backend);
+    expect(unregisterProtocolSchemes(['myapp', 'myapp2'])).toBe(false);
+  });
+});