Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

2.8 KB
Raw Blame
/**
 * Whether the composer's microphone can be opened at all, and — when it cannot — which of the
 * three ways it was closed. The distinction is the whole point: only one of the three is about
 * permission, and telling a user to grant a permission the browser never offered is a dead end.
 *
 * The first two are decided BEFORE anything is asked, because on those two nothing is ever asked:
 *
 *   - The page may sit on an origin the browser does not treat as secure. There `navigator.
 *     mediaDevices` does not exist — not "was refused", does not exist — so no prompt is shown
 *     and none can be granted. A plain `http://` address that is not `localhost` is that case, and
 *     it is the one users hit: the desktop App's own window runs on `http://localhost:<port>` and
 *     is fine, while the same server opened at `http://10.0.0.5:7777` in a browser is not.
 *   - Otherwise the browser may simply have no capture support.
 *
 * What is left is asked for with `getUserMedia`, and its refusal is named by
 * {@link microphoneRefusal}. Neither function reaches for a browser global, so both are testable
 * without one.
 */

/** Why the microphone cannot be asked for at all, decided before anything is asked. */
export type MicrophoneObstacle = "insecure" | "unsupported";

/** The slice of the page that decides it. */
export interface MicrophoneEnvironment {
  isSecureContext: boolean;
  mediaDevices?: { getUserMedia?: unknown } | undefined;
}

/**
 * The obstacle in the way, or null when the microphone may be asked for. An insecure origin is
 * named as such even if it somehow exposes `mediaDevices`: the address is what would refuse the
 * request, so that is what the notice has to say.
 */
export function microphoneObstacle(env: MicrophoneEnvironment): MicrophoneObstacle | null {
  if (!env.isSecureContext) return "insecure";
  if (typeof env.mediaDevices?.getUserMedia !== "function") return "unsupported";
  return null;
}

/** What a refused `getUserMedia` was refused for, as far as the browser's error name says. */
export type MicrophoneRefusal = "denied" | "missing" | "busy" | "other";

/**
 * The refusal, in the terms the notice can act on: `denied` is the user's to undo (in the address
 * bar, not here), `missing` means no device, `busy` another program holding it. Anything else —
 * including a non-Error rejection, which some browsers produce — is `other`, which is where a
 * guess would otherwise go.
 */
export function microphoneRefusal(error: unknown): MicrophoneRefusal {
  const name = error instanceof Error ? error.name : "";
  if (name === "NotAllowedError" || name === "SecurityError") return "denied";
  if (name === "NotFoundError" || name === "OverconstrainedError") return "missing";
  if (name === "NotReadableError" || name === "AbortError") return "busy";
  return "other";
}