webcanvas-wasm 0.1.0

package/src/gecko/runtime.js

@@ -0,0 +1,717 @@
+// @ts-check
+
+/**
+ * Typed wrapper over the vendored Gecko WASM engine.
+ *
+ * The engine class is intentionally thin and leaky: `evalChrome` swallows
+ * exceptions and returns `''`, it cannot await promises, and it has no way to
+ * report whether a page exists yet. This module keeps the escape hatch (the
+ * raw `run()` command queue stays reachable on `raw`) but presents a surface
+ * where every fallible call returns a discriminated result instead of a value
+ * that might silently be an error.
+ *
+ * Types live in `types/engine.d.ts` and `types/session.d.ts`.
+ */
+
+/**
+ * @typedef {import('../../types/engine.js').Gecko} Gecko
+ * @typedef {import('../../types/engine.js').GeckoEnv} GeckoEnv
+ * @typedef {import('../../types/engine.js').GeckoOptions} GeckoOptions
+ * @typedef {import('../../types/session.js').SessionOptions} SessionOptions
+ * @typedef {import('../../types/session.js').GeckoSession} GeckoSession
+ * @typedef {import('../../types/session.js').SessionState} SessionState
+ * @typedef {import('../../types/session.js').ElementSnapshot} ElementSnapshot
+ * @typedef {import('../../types/session.js').WaitForOptions} WaitForOptions
+ */
+
+/**
+ * Restated locally because a JSDoc `@typedef` that imports a generic alias
+ * collapses it to a non-generic type. The public shape is still enforced by
+ * `GeckoSession`, which the factory's `@returns` tag is checked against.
+ *
+ * @template T
+ * @typedef {{ readonly ok: true, readonly value: T }
+ *   | { readonly ok: false, readonly error: string }} EvalResult
+ */
+
+/**
+ * @template T
+ * @typedef {(value: unknown) => value is T} TypeGuard
+ */
+
+/**
+ * @typedef {{ timeoutMs?: number }} EvaluateOptions
+ */
+
+/** `o` field of the bridge envelope: promise has not settled yet. */
+const PENDING = 0;
+
+/**
+ * Raised when a snippet throws, the page cannot be reached, or a shape guard
+ * rejects. Kept distinct from a generic `Error` so callers can distinguish a
+ * WebView failure from a bug in their own code.
+ */
+export class GeckoEvalError extends Error {
+  /**
+   * @param {string} message
+   * @param {'not-ready' | 'no-page' | 'no-result' | 'throw' | 'shape' | 'timeout'} code
+   */
+  constructor(message, code) {
+    super(message);
+    this.name = 'GeckoEvalError';
+    this.code = code;
+  }
+}
+
+/** @param {unknown} value @returns {value is GeckoEvalError} */
+export function isGeckoEvalError(value) {
+  return value instanceof GeckoEvalError;
+}
+
+const DEFAULT_READY_TIMEOUT_MS = 20_000;
+const DEFAULT_POLL_INTERVAL_MS = 100;
+const DEFAULT_EVAL_TIMEOUT_MS = 15_000;
+
+/**
+ * Injected into the page to turn an arbitrary completion value into something
+ * safely transferable. `evalChrome` stringifies its result, and most values
+ * are not strings, so each value gets its own `JSON.stringify` attempt with a
+ * `String()` fallback. That keeps the failure modes distinguishable: a thrown
+ * snippet reports a failure, a circular value degrades to its text form instead
+ * of masquerading as a crash.
+ */
+const SERIALIZE = 'let s;try{s=JSON.stringify(v)}catch(e){s=JSON.stringify(String(v))}';
+
+/**
+ * Page-side error formatter, injected into the page.
+ *
+ * `String(error)` keeps the message but drops the type, while `error.stack` in
+ * the embed-chrome sandbox is a bare wrapper trace with no message in it at all.
+ * Combining them keeps failures diagnosable instead of returning a trace that
+ * only mentions `@embed-chrome`.
+ */
+const DESCRIBE_ERROR =
+  'e=>{const head=(e&&e.name?e.name+": ":"")+String((e&&e.message)||e);const st=String((e&&e.stack)||"");return st&&st.indexOf(head)<0?head+"\\n"+st:head}';
+
+/**
+ * Builds the snippet that runs `code` in the page.
+ *
+ * Synchronous values answer immediately. A thenable is parked on `window[key]`
+ * and reported as `o:3`, which is the only case that costs a poll, so the fast
+ * path stays free of round-trips.
+ *
+ * @param {string} code
+ * @param {string} key
+ * @returns {string}
+ */
+function envelopeSource(code, key) {
+  return (
+    '(()=>{const d=' +
+    DESCRIBE_ERROR +
+    ';const k=' +
+    JSON.stringify(key) +
+    ';' +
+    'const done=v=>{try{let s=JSON.stringify(v);window[k]={o:1,s}}catch(e){window[k]={o:1,s:JSON.stringify(String(v))}}};' +
+    'try{const v=eval(' +
+    JSON.stringify(code) +
+    ');' +
+    'if(v&&typeof v.then==="function"){window[k]={o:0};Promise.resolve(v).then(done,e=>{window[k]={o:2,e:d(e)}});return JSON.stringify({o:3})}' +
+    SERIALIZE +
+    'return JSON.stringify({o:1,s})}' +
+    'catch(e){return JSON.stringify({o:0,e:d(e)})}})()'
+  );
+}
+
+/** `o:3` marks a snippet whose completion value was a promise. */
+const PENDING_PROMISE = 3;
+
+/** Monotonic source for the private global a pending promise is parked on. */
+let promiseKeySequence = 0;
+const nextPromiseKey = () => `__webcanvasWasm${(promiseKeySequence += 1).toString(36)}`;
+
+/**
+ * @param {string} source
+ * @returns {{ ok: true, value: unknown } | { ok: false, error: string } | null}
+ */
+function decodeEnvelope(source) {
+  if (typeof source !== 'string' || !source) return null;
+  let payload;
+  try {
+    payload = JSON.parse(source);
+  } catch {
+    // The page returned something that is not our envelope, which means the
+    // snippet bypassed `eval` (for example it returned a raw object literal
+    // evaluated in another realm). Surface it verbatim rather than guessing.
+    return { ok: true, value: source };
+  }
+  if (!payload || typeof payload !== 'object') return { ok: true, value: payload };
+  const envelope = /** @type {{ o?: number, s?: string, e?: string }} */ (
+    /** @type {unknown} */ (payload)
+  );
+  if (envelope.o === 0) return { ok: false, error: envelope.e || 'snippet threw' };
+  if (envelope.o === PENDING_PROMISE) {
+    // The snippet returned a promise, so its value is parked on a private
+    // global. Pass the marker through so the caller knows to poll; decoding it
+    // as a normal value here would silently return `null` for every promise.
+    return { ok: true, value: payload };
+  }
+  if (typeof envelope.s !== 'string') return { ok: true, value: null };
+  try {
+    return { ok: true, value: JSON.parse(envelope.s) };
+  } catch {
+    return { ok: true, value: envelope.s };
+  }
+}
+
+const sleep = (/** @type {number} */ ms) => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Flattens a page element into plain data.
+ *
+ * `query` cannot hand back a live `Element`: the bridge is string-based, so
+ * anything structured would arrive mangled. Projecting to a snapshot keeps the
+ * promise honest about what crosses the boundary.
+ */
+const SNAPSHOT = `el=>{const r=el.getBoundingClientRect();return{tag:el.tagName.toLowerCase(),id:el.id||null,className:el.getAttribute('class'),text:(el.textContent||'').trim().slice(0,2000),html:(el.outerHTML||'').slice(0,2000),attrs:Object.fromEntries([...el.attributes].map(a=>[a.name,a.value])),visible:r.width>0&&r.height>0,rect:{x:r.x,y:r.y,width:r.width,height:r.height}}}`;
+
+/**
+ * @param {Partial<SessionOptions>} options
+ * @returns {GeckoSession}
+ */
+export function createGeckoRuntime(options = {}) {
+  const host = options.host || globalThis.window;
+  const canvas = /** @type {HTMLCanvasElement | undefined} */ (options.canvas);
+  const loadModule = options.loadModule || (async url => import(url));
+  const bundleUrl = options.bundleUrl || '/engine/gecko.js';
+  const wasmUrl = options.wasmUrl || '/engine/gecko.wasm.zst';
+  const profile = options.profile || 'webcanvas-wasm';
+  const onLog = options.onLog || (() => {});
+  const onError = options.onError || (() => {});
+
+  /** @type {Gecko | null} */
+  let instance = null;
+  /** @type {Promise<Gecko> | null} */
+  let initPromise = null;
+  /** @type {string | null} */
+  let currentUrl = null;
+  /** @type {SessionState} */
+  let state = 'idle';
+  /** Bumped on every navigation so a stale watcher cannot win a race. */
+  let navigationGeneration = 0;
+  let hasNavigated = false;
+  let navigationMark = '';
+
+  /** @param {string} reason @returns {EvalResult<never>} */
+  const unavailable = reason => ({ ok: false, error: reason });
+
+  /** @type {Set<(state: SessionState) => void>} */
+  const listeners = new Set();
+
+  /**
+   * Notifies subscribers that observable session state changed. Safe to call
+   * after teardown: the set is only read.
+   */
+  function emit() {
+    for (const listener of listeners) {
+      try {
+        listener(state);
+      } catch (error) {
+        onError(error);
+      }
+    }
+  }
+
+  /**
+   * @param {SessionState} next
+   */
+  function setState(next) {
+    if (state === next) return;
+    state = next;
+    emit();
+  }
+
+  /**
+   * Subscribe to session state changes. The listener fires immediately with the
+   * current state, which keeps `useSyncExternalStore` happy.
+   *
+   * @param {(state: SessionState) => void} listener
+   * @returns {() => void} unsubscribe
+   */
+  function subscribe(listener) {
+    listeners.add(listener);
+    listener(state);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+
+  function wispUrl() {
+    const protocol = host.location?.protocol === 'https:' ? 'wss:' : 'ws:';
+    return `${protocol}//${host.location?.host || '127.0.0.1:8080'}/wisp/`;
+  }
+
+  /**
+   * Issues a snippet and decodes the reply. Resolves to `null` when the engine
+   * produced no reply at all, which is how a missing page shows up.
+   * @param {string} source
+   * @returns {Promise<{ ok: true, value: unknown } | { ok: false, error: string } | null>}
+   */
+  async function send(source) {
+    if (!instance) return { ok: false, error: 'Gecko is not ready' };
+    if (typeof instance.evalChrome !== 'function') {
+      return { ok: false, error: 'engine build does not expose evalChrome' };
+    }
+    try {
+      return decodeEnvelope(await instance.evalChrome(source));
+    } catch (error) {
+      return { ok: false, error: String((error && /** @type {Error} */ (error).message) || error) };
+    }
+  }
+
+  /**
+   * Issues a snippet and returns the reply untouched.
+   *
+   * Internal probes already define their own reply format, so they must bypass
+   * {@link decodeEnvelope} rather than being misread as a wrapped value.
+   * @param {string} source
+   * @returns {Promise<string | null>}
+   */
+  async function sendRaw(source) {
+    if (!instance) return null;
+    if (typeof instance.evalChrome !== 'function') return null;
+    try {
+      const value = await instance.evalChrome(source);
+      return typeof value === 'string' ? value : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Marks the document currently on screen, so a later navigation can be told
+   * apart from it.
+   *
+   * `readyState` on its own cannot tell "the new page has loaded" from "the old
+   * page is still loaded": both report something other than `loading`, so a
+   * caller waiting on it can resume against the document it was trying to
+   * leave. Stamping the outgoing document and waiting for the mark to vanish is
+   * redirect-agnostic, unlike comparing URLs.
+   *
+   * @returns {string} the mark to wait for the disappearance of
+   */
+  function stampCurrentDocument() {
+    const mark = `g${++navigationGeneration}`;
+    try {
+      // Best effort: a document that cannot be stamped simply degrades the
+      // later wait to the readyState check on its own.
+      void Promise.resolve(
+        instance?.evalChrome(
+          `document.documentElement&&document.documentElement.setAttribute("data-gecko-nav",${JSON.stringify(mark)})`
+        )
+      ).catch(() => {});
+    } catch {
+      // Same: never let bookkeeping fail a navigation.
+    }
+    return mark;
+  }
+
+  /**
+   * Predicate that holds only once the marked document has been replaced *and*
+   * its replacement has finished loading.
+   *
+   * @param {string} mark
+   * @returns {string}
+   */
+  function navigatedAwayFrom(mark) {
+    return (
+      `((${JSON.stringify(mark)})!==` +
+      `((document.documentElement&&document.documentElement.getAttribute("data-gecko-nav"))||null)` +
+      `&&document.readyState!=="loading")`
+    );
+  }
+
+  /**
+   * Polls the page until the document we navigated away from is gone and the
+   * new one has settled. Navigation is dispatched without awaiting it, so this
+   * is the only signal that the new document is actually scriptable.
+   * @param {number} generation
+   * @param {string} mark
+   */
+  function watchForPageReady(generation, mark) {
+    const deadline = Date.now() + DEFAULT_READY_TIMEOUT_MS;
+    const poll = async () => {
+      while (state !== 'destroyed' && generation === navigationGeneration) {
+        if (Date.now() > deadline) {
+          // The engine is healthy even if the document never settles, so
+          // report ready rather than stranding the caller in 'loading'.
+          if (state === 'loading') setState('ready');
+          return;
+        }
+        const swapped = await sendRaw(navigatedAwayFrom(mark));
+        // `sendRaw` stringifies, so a pending answer arrives as 'false'.
+        if (swapped && swapped !== 'false') {
+          setState('ready');
+          return;
+        }
+        await sleep(DEFAULT_POLL_INTERVAL_MS);
+      }
+    };
+    void poll().catch(error => onError(error));
+  }
+
+  async function init() {
+    if (instance) return instance;
+    if (initPromise) return initPromise;
+    if (!canvas) throw new Error('Canvas is required');
+    if (!host?.crossOriginIsolated) throw new Error('Cross-origin isolation is required');
+    setState('booting');
+    initPromise = (async () => {
+      const module = await loadModule(bundleUrl);
+      const GeckoCtor = module.Gecko;
+      /** @type {import('../../types/engine.js').GeckoOptions} */
+      const engineOptions = {
+        canvas,
+        width: Math.max(1024, Math.round(Number(host.innerWidth) || 1280)),
+        height: Math.max(720, Math.round(Number(host.innerHeight) || 720)),
+        profile,
+        wasm: { url: wasmUrl, compressed: true },
+        wispUrl: wispUrl(),
+        env: /** @type {GeckoEnv} */ ({
+          // Heavy pages exhaust the engine's 64 MB stack under the Wasm JIT.
+          GECKO_NOWASMJIT: '1',
+          ...options.env
+        }),
+        print: value => onLog(String(value)),
+        printErr: value => onLog(String(value))
+      };
+      const gecko = new GeckoCtor(engineOptions);
+      await gecko.init();
+      instance = gecko;
+      setState('ready');
+      return gecko;
+    })().catch(error => {
+      initPromise = null;
+      instance = null;
+      setState('idle');
+      throw error;
+    });
+    return initPromise;
+  }
+
+  /**
+   * @param {string} value
+   * @returns {string}
+   */
+  function navigate(value) {
+    if (!instance) throw new Error('Gecko is not ready');
+    const url = normalizeHttpUrl(value);
+    navigationMark = stampCurrentDocument();
+    currentUrl = url;
+    emit();
+    hasNavigated = true;
+    setState('loading');
+    navigationGeneration += 1;
+    Promise.resolve(instance.load(url)).catch(error => onError(error));
+    watchForPageReady(navigationGeneration, navigationMark);
+    return url;
+  }
+
+  /** @returns {string | null} */
+  function reload() {
+    if (!currentUrl) return null;
+    return navigate(currentUrl);
+  }
+
+  /**
+   * @param {number} [width]
+   * @param {number} [height]
+   * @returns {Promise<void>}
+   */
+  function resize(width, height) {
+    if (!instance?.resize) return Promise.resolve();
+    const w = Math.max(1024, Math.round(Number(width ?? host.innerWidth) || 1280));
+    const h = Math.max(720, Math.round(Number(height ?? host.innerHeight) || 720));
+    // `app.js` calls this from a resize listener without awaiting, so a
+    // rejection must be routed rather than left unhandled.
+    return Promise.resolve(instance.resize(w, h)).then(() => undefined, error => {
+      onError(error);
+    });
+  }
+
+  /**
+   * Waits for a parked promise value and decodes the slot.
+   * @param {string} key
+   * @param {number} timeoutMs
+   * @returns {Promise<unknown>}
+   */
+  async function drainPromise(key, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+      const reply = await sendRaw(`(()=>{const r=window[${JSON.stringify(key)}];return r?JSON.stringify(r):null})()`);
+      if (typeof reply === 'string') {
+        let parsed = null;
+        try {
+          parsed = JSON.parse(reply);
+        } catch {
+          parsed = null;
+        }
+        const slot = parsed && typeof parsed === 'object' ? parsed : null;
+        const status = slot ? Number(slot.o) || PENDING : PENDING;
+        if (status !== PENDING) {
+          void sendRaw(`(()=>{try{delete window[${JSON.stringify(key)}]}catch(e){};return true})()`);
+          if (status === 2) {
+            throw new GeckoEvalError(String(slot.e || 'promise rejected'), 'throw');
+          }
+          const raw = slot.s;
+          if (typeof raw !== 'string') return null;
+          try {
+            return JSON.parse(raw);
+          } catch {
+            return raw;
+          }
+        }
+      }
+      await sleep(DEFAULT_POLL_INTERVAL_MS);
+    }
+    void sendRaw(`(()=>{try{delete window[${JSON.stringify(key)}]}catch(e){};return true})()`);
+    throw new GeckoEvalError(`promise did not settle within ${timeoutMs}ms`, 'timeout');
+  }
+
+  /**
+   * Evaluate a snippet in the loaded page and return its value.
+   *
+   * Throws {@link GeckoEvalError} on any failure, which is the ergonomic
+   * default: `await session.eval('document.title')` just gives you the title.
+   * Wrap a call in {@link attempt} when you want a value instead of a throw.
+   *
+   * A promise-returning snippet is awaited automatically, so there is no
+   * separate async entry point to remember.
+   *
+   * @template T
+   * @param {string} code
+   * @param {EvaluateOptions} [evaluateOptions]
+   * @returns {Promise<T>}
+   */
+  async function evaluate(code, evaluateOptions = {}) {
+    const timeoutMs = evaluateOptions.timeoutMs ?? DEFAULT_EVAL_TIMEOUT_MS;
+    if (!instance) throw new GeckoEvalError('Gecko is not ready', 'not-ready');
+    if (!hasNavigated) throw new GeckoEvalError('no page has been loaded yet', 'no-page');
+
+    const key = nextPromiseKey();
+    const result = await send(envelopeSource(code, key));
+    if (result === null) throw new GeckoEvalError('page did not return a result', 'no-result');
+    if (!result.ok) throw new GeckoEvalError(result.error, 'throw');
+
+    const value = result.value;
+    if (value && typeof value === 'object' && (/** @type {{o?: number}} */ (value).o) === PENDING_PROMISE) {
+      return /** @type {T} */ (await drainPromise(key, timeoutMs));
+    }
+    return /** @type {T} */ (value);
+  }
+
+  /**
+   * Runs a call and converts a thrown {@link GeckoEvalError} into a result
+   * union, so the common case can stay throw-based without losing the
+   * non-throwing form where it is genuinely useful.
+   *
+   * @template T
+   * @param {() => Promise<T> | T} fn
+   * @returns {Promise<EvalResult<T>>}
+   */
+  async function attempt(fn) {
+    try {
+      return { ok: true, value: await fn() };
+    } catch (error) {
+      const message =
+        error instanceof GeckoEvalError
+          ? error.message
+          : String((error && /** @type {Error} */ (error).message) || error);
+      return { ok: false, error: message };
+    }
+  }
+
+  /**
+   * @template T
+   * @param {string} code
+   * @param {TypeGuard<T>} guard
+   * @returns {Promise<T>}
+   */
+  async function evalJson(code, guard) {
+    const value = await evaluate(code);
+    if (!guard(value)) {
+      throw new GeckoEvalError(
+        `page value did not match the expected shape (got ${describe(value)})`,
+        'shape'
+      );
+    }
+    return value;
+  }
+
+  /**
+   * Navigate and wait until the new document is scriptable.
+   *
+   * This is the call most consumers want: `navigate()` only dispatches, so
+   * evaluating immediately afterwards races the load. `open()` closes that gap.
+   *
+   * @param {string} value
+   * @param {number} [timeoutMs]
+   * @returns {Promise<string>} the normalised URL
+   */
+  async function open(value, timeoutMs = DEFAULT_READY_TIMEOUT_MS * 3) {
+    const url = navigate(value);
+    await waitFor(navigatedAwayFrom(navigationMark), {
+      timeoutMs,
+      intervalMs: 250
+    });
+    return url;
+  }
+
+  /**
+   * @deprecated Promises are awaited automatically by `eval`. Kept as an alias
+   * so existing call sites keep working.
+   * @template T
+   * @param {string} code
+   * @param {number} [timeoutMs]
+   * @returns {Promise<T>}
+   */
+  function evalAsync(code, timeoutMs) {
+    return evaluate(code, timeoutMs === undefined ? undefined : { timeoutMs });
+  }
+
+  /**
+   * @param {string} predicate
+   * @param {WaitForOptions} [waitOptions]
+   * @returns {Promise<boolean>}
+   */
+  async function waitFor(predicate, waitOptions = {}) {
+    const timeoutMs = waitOptions.timeoutMs ?? 15_000;
+    const intervalMs = waitOptions.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+      const result = await attempt(() => evaluate(predicate));
+      if (result.ok && result.value) return true;
+      await sleep(intervalMs);
+    }
+    return false;
+  }
+
+  /**
+   * @template T
+   * @param {string} selector
+   * @returns {Promise<T | null>}
+   */
+  async function query(selector) {
+    return evaluate(`(()=>{const el=document.querySelector(${JSON.stringify(selector)});return el?(${SNAPSHOT})(el):null})()`);
+  }
+
+  /**
+   * @template T
+   * @param {string} selector
+   * @returns {Promise<T[]>}
+   */
+  async function queryAll(selector) {
+    return evaluate(`[...document.querySelectorAll(${JSON.stringify(selector)})].map(el=>(${SNAPSHOT})(el))`);
+  }
+
+  /**
+   * @param {string} selector
+   * @returns {Promise<string>}
+   */
+  async function text(selector) {
+    return evaluate(
+      `(()=>{const el=document.querySelector(${JSON.stringify(selector)});return el?(el.textContent||'').trim():''})()`
+    );
+  }
+
+  /**
+   * @param {string} name
+   * @param {string} selector
+   * @returns {Promise<string | null>}
+   */
+  async function attr(name, selector) {
+    return evaluate(
+      `(()=>{const el=document.querySelector(${JSON.stringify(selector)});return el?el.getAttribute(${JSON.stringify(name)}):null})()`
+    );
+  }
+
+  /**
+   * @param {string} selector
+   * @returns {Promise<boolean>}
+   */
+  async function click(selector) {
+    return evaluate(
+      `(()=>{const el=document.querySelector(${JSON.stringify(selector)});if(!el)return false;el.click();return true})()`
+    );
+  }
+
+  function destroy() {
+    if (!instance) return;
+    navigationGeneration += 1;
+    try {
+      instance.destroy();
+    } catch (error) {
+      onError(error);
+    }
+    instance = null;
+    initPromise = null;
+    setState('destroyed');
+  }
+
+  return {
+    init,
+    navigate,
+    open,
+    reload,
+    resize,
+    evaluate,
+    eval: evaluate,
+    evalJson,
+    evalAsync,
+    attempt,
+    waitFor,
+    query,
+    queryAll,
+    text,
+    attr,
+    click,
+    destroy,
+    subscribe,
+    get raw() {
+      return instance;
+    },
+    get state() {
+      return state;
+    },
+    get ready() {
+      return Boolean(instance);
+    },
+    get currentUrl() {
+      return currentUrl;
+    }
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describe(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return `array(${value.length})`;
+  return typeof value;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function normalizeHttpUrl(value) {
+  const raw = String(value || '').trim();
+  if (!raw) throw new Error('Enter a URL');
+  const candidate = /^[a-z][a-z0-9+.-]*:/i.test(raw) ? raw : `https://${raw}`;
+  const url = new URL(candidate);
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error('Only http or https URLs are supported');
+  }
+  return url.href;
+}