@blario/react-native 0.0.0 → 0.1.1

package/src/snapshot/text-layout.ts

@@ -0,0 +1,59 @@
+import type { Rect } from '../host/rect.ts';
+
+export interface PositionedText {
+  rect: Rect;
+  text: string;
+  heading: boolean;
+}
+
+const SAME_LINE_OVERLAP = 0.5;
+const LINE_SEPARATOR = '  ';
+
+function verticalOverlap(first: Rect, second: Rect): number {
+  const top = Math.max(first.y, second.y);
+  const bottom = Math.min(first.y + first.height, second.y + second.height);
+  return Math.max(0, bottom - top);
+}
+
+function sharesLine(line: PositionedText[], candidate: PositionedText): boolean {
+  const reference = line[line.length - 1];
+  if (reference === undefined || reference.heading || candidate.heading) {
+    return false;
+  }
+  const shorter = Math.min(reference.rect.height, candidate.rect.height);
+  return shorter > 0 && verticalOverlap(reference.rect, candidate.rect) / shorter >= SAME_LINE_OVERLAP;
+}
+
+export function groupIntoLines(blocks: PositionedText[]): string[] {
+  const sorted = [...blocks].sort((left, right) => left.rect.y - right.rect.y || left.rect.x - right.rect.x);
+  const lines: PositionedText[][] = [];
+  for (const block of sorted) {
+    const current = lines[lines.length - 1];
+    if (current !== undefined && sharesLine(current, block)) {
+      current.push(block);
+    } else {
+      lines.push([block]);
+    }
+  }
+  return lines.map((line) => {
+    const joined = [...line].sort((left, right) => left.rect.x - right.rect.x).map((block) => block.text).join(LINE_SEPARATOR);
+    return line.length === 1 && line[0]?.heading === true ? `# ${joined}` : joined;
+  });
+}
+
+export function limitCharacters(lines: string[], maxChars: number): string[] {
+  if (maxChars <= 0) {
+    return lines;
+  }
+  const kept: string[] = [];
+  let used = 0;
+  for (const line of lines) {
+    if (used + line.length > maxChars) {
+      kept.push('…');
+      break;
+    }
+    kept.push(line);
+    used += line.length + 1;
+  }
+  return kept;
+}

package/src/snapshot/view.ts

@@ -0,0 +1,87 @@
+import { collectText, precedingText } from '../fiber/text.ts';
+import { propsOf } from '../fiber/reader.ts';
+import type { Fiber } from '../fiber/types.ts';
+import type { Rect } from '../host/rect.ts';
+import { iconNameIn } from './icon.ts';
+import type { Offscreen } from './visibility.ts';
+import type { ElementKind } from './kinds.ts';
+import {
+  accessibilityFlagsOf,
+  explicitLabelOf,
+  inputTypeOf,
+  placeholderOf,
+  roleOf,
+  testIdOf,
+  textValueOf,
+} from './properties.ts';
+
+const BUTTON_LABEL_LIMIT = 80;
+const INPUT_LABEL_LIMIT = 40;
+
+export interface ElementView {
+  kind: ElementKind;
+  label: string;
+  icon: string | null;
+  testID: string | null;
+  role: string | null;
+  type: string | null;
+  placeholder: string | null;
+  value: string | null;
+  checked: boolean | null;
+  disabled: boolean;
+  expanded: boolean | null;
+  selected: boolean | null;
+  scroll: string | null;
+  offscreen: Offscreen | null;
+  rect: Rect;
+}
+
+function labelFor(kind: ElementKind, fiber: Fiber, ancestors: Fiber[]): string {
+  const explicit = explicitLabelOf(propsOf(fiber));
+  if (explicit !== null) {
+    return explicit;
+  }
+  if (kind === 'button') {
+    return collectText(fiber, BUTTON_LABEL_LIMIT);
+  }
+  if (kind === 'text_input' || kind === 'switch') {
+    return precedingText(ancestors, fiber, INPUT_LABEL_LIMIT);
+  }
+  return '';
+}
+
+export interface ViewSource {
+  kind: ElementKind;
+  fiber: Fiber;
+  ancestors: Fiber[];
+  rect: Rect;
+  scroll: string | null;
+  offscreen?: Offscreen | null;
+}
+
+export function buildView(source: ViewSource): ElementView {
+  const { kind, fiber, ancestors, rect, scroll } = source;
+  const offscreen = source.offscreen ?? null;
+  const props = propsOf(fiber);
+  const flags = accessibilityFlagsOf(props);
+  const isInput = kind === 'text_input';
+  const isSwitch = kind === 'switch';
+  const role = roleOf(props);
+  return {
+    kind,
+    label: labelFor(kind, fiber, ancestors),
+    icon: kind === 'button' ? iconNameIn(fiber) : null,
+    testID: testIdOf(props),
+    role: kind === 'button' && role === 'button' ? null : role,
+    type: isInput ? inputTypeOf(props) : isSwitch ? 'checkbox' : null,
+    placeholder: isInput ? placeholderOf(props) : null,
+    value: isInput ? textValueOf(props) : null,
+    checked: isSwitch ? props.value === true : null,
+    disabled: isInput ? flags.disabled || props.editable === false : flags.disabled,
+    expanded: flags.expanded,
+    selected: flags.selected,
+    scroll,
+    offscreen,
+    rect,
+  };
+}

package/src/snapshot/visibility.ts

@@ -0,0 +1,63 @@
+import type { Fiber } from '../fiber/types.ts';
+import { intersects, isVisibleIn, type Rect, type Size } from '../host/rect.ts';
+import { measureScrollGeometry, type ScrollGeometry } from './scroll.ts';
+
+export type ScrollGeometries = Map<Fiber, ScrollGeometry | null>;
+
+export async function measureScrollGeometries(containers: Iterable<Fiber>): Promise<ScrollGeometries> {
+  const unique = [...new Set(containers)];
+  const entries = await Promise.all(
+    unique.map(async (container): Promise<[Fiber, ScrollGeometry | null]> => [container, await measureScrollGeometry(container)]),
+  );
+  return new Map(entries);
+}
+
+export type Offscreen = 'above' | 'below' | 'left' | 'right';
+
+export type Visibility =
+  | { kind: 'visible' }
+  | { kind: 'offscreen'; direction: Offscreen; distance: number }
+  | { kind: 'hidden' };
+
+const VISIBLE: Visibility = { kind: 'visible' };
+const HIDDEN: Visibility = { kind: 'hidden' };
+
+function offscreenAgainst(rect: Rect, geometry: ScrollGeometry): Visibility {
+  const { viewport, horizontal } = geometry;
+  if (horizontal) {
+    return rect.x >= viewport.x + viewport.width
+      ? { kind: 'offscreen', direction: 'right', distance: rect.x - (viewport.x + viewport.width) }
+      : { kind: 'offscreen', direction: 'left', distance: viewport.x - (rect.x + rect.width) };
+  }
+  return rect.y >= viewport.y + viewport.height
+    ? { kind: 'offscreen', direction: 'below', distance: rect.y - (viewport.y + viewport.height) }
+    : { kind: 'offscreen', direction: 'above', distance: viewport.y - (rect.y + rect.height) };
+}
+
+export function classifyVisibility(rect: Rect, window: Size, containers: Fiber[], geometries: ScrollGeometries): Visibility {
+  if (rect.width <= 0 || rect.height <= 0) {
+    return HIDDEN;
+  }
+  for (let index = containers.length - 1; index >= 0; index -= 1) {
+    const container = containers[index];
+    const geometry = container === undefined ? null : (geometries.get(container) ?? null);
+    if (geometry !== null && !intersects(rect, geometry.viewport)) {
+      return isVisibleIn(geometry.viewport, window) ? offscreenAgainst(rect, geometry) : HIDDEN;
+    }
+  }
+  return isVisibleIn(rect, window) ? VISIBLE : HIDDEN;
+}
+
+function isBeyondWindowEdge(rect: Rect, window: Size): boolean {
+  return rect.x >= window.width || rect.x + rect.width <= 0;
+}
+
+export function keepInTextTree(visibility: Visibility, rect: Rect, window: Size, viewportOnly: boolean): boolean {
+  if (visibility.kind === 'offscreen' && (visibility.direction === 'left' || visibility.direction === 'right')) {
+    return false;
+  }
+  if (visibility.kind === 'hidden' && isBeyondWindowEdge(rect, window)) {
+    return false;
+  }
+  return !viewportOnly || visibility.kind === 'visible';
+}

package/src/snapshot/wrappers.ts

@@ -0,0 +1,69 @@
+import { propsOf } from '../fiber/reader.ts';
+import type { Rect } from '../host/rect.ts';
+import type { Candidate } from './collect.ts';
+import type { Offscreen } from './visibility.ts';
+
+export interface MeasuredCandidate {
+  candidate: Candidate;
+  rect: Rect;
+  offscreen: Offscreen | null;
+  distance: number;
+}
+
+const RECT_TOLERANCE = 1;
+
+function handlerOf(candidate: Candidate): unknown {
+  const props = propsOf(candidate.fiber);
+  switch (candidate.kind) {
+    case 'button':
+      return props.onPress;
+    case 'text_input':
+      return props.onChangeText ?? props.onChange;
+    case 'switch':
+      return props.onValueChange;
+    case 'scroll':
+      return null;
+  }
+}
+
+function isSameRect(first: Rect, second: Rect): boolean {
+  return (
+    Math.abs(first.x - second.x) <= RECT_TOLERANCE &&
+    Math.abs(first.y - second.y) <= RECT_TOLERANCE &&
+    Math.abs(first.width - second.width) <= RECT_TOLERANCE &&
+    Math.abs(first.height - second.height) <= RECT_TOLERANCE
+  );
+}
+
+function isWrapperOf(outer: MeasuredCandidate, inner: MeasuredCandidate): boolean {
+  if (outer.candidate.kind !== inner.candidate.kind || outer.candidate.kind === 'scroll') {
+    return false;
+  }
+  const sharedHandler = handlerOf(outer.candidate) !== undefined && handlerOf(outer.candidate) === handlerOf(inner.candidate);
+  return sharedHandler || isSameRect(outer.rect, inner.rect);
+}
+
+export function dropWrapperDuplicates(measured: MeasuredCandidate[]): MeasuredCandidate[] {
+  const byFiber = new Map<unknown, MeasuredCandidate>(measured.map((entry) => [entry.candidate.fiber, entry]));
+  const wrappers = new Set<MeasuredCandidate>();
+  for (const inner of measured) {
+    for (const ancestor of inner.candidate.ancestors) {
+      const outer = byFiber.get(ancestor);
+      if (outer !== undefined && isWrapperOf(outer, inner)) {
+        wrappers.add(outer);
+      }
+    }
+  }
+  return measured.filter((entry) => !wrappers.has(entry));
+}
+
+const OFFSCREEN_LIMIT = 30;
+
+export function limitOffscreen(measured: MeasuredCandidate[]): MeasuredCandidate[] {
+  const hidden = measured.filter((entry) => entry.offscreen !== null && entry.candidate.kind !== 'scroll');
+  if (hidden.length <= OFFSCREEN_LIMIT) {
+    return measured;
+  }
+  const dropped = new Set(hidden.sort((left, right) => left.distance - right.distance).slice(OFFSCREEN_LIMIT));
+  return measured.filter((entry) => !dropped.has(entry));
+}

package/src/telemetry/SdkErrorBoundary.tsx

@@ -0,0 +1,28 @@
+import React, { Component, type ReactNode } from 'react';
+
+import { reportSdkError } from './sdk-reporter.ts';
+
+interface SdkErrorBoundaryProps {
+  context: string;
+  children: ReactNode;
+}
+
+interface SdkErrorBoundaryState {
+  failed: boolean;
+}
+
+export class SdkErrorBoundary extends Component<SdkErrorBoundaryProps, SdkErrorBoundaryState> {
+  override state: SdkErrorBoundaryState = { failed: false };
+
+  static getDerivedStateFromError(): SdkErrorBoundaryState {
+    return { failed: true };
+  }
+
+  override componentDidCatch(error: Error): void {
+    reportSdkError(this.props.context, error);
+  }
+
+  override render(): React.ReactNode {
+    return this.state.failed ? null : this.props.children;
+  }
+}

package/src/telemetry/build-info.generated.ts

@@ -0,0 +1,2 @@
+export const SENTRY_DSN: string = "https://a8feb37b0161b10ad73d64ff7c9911e0@o4507510402383872.ingest.us.sentry.io/4511661901414400";
+export const SENTRY_ENVIRONMENT: string = "production-react-native";

package/src/telemetry/envelope.ts

@@ -0,0 +1,83 @@
+export type StateSnapshot = Record<string, string | number | boolean>;
+
+export interface StackFrame {
+  function?: string;
+  filename: string;
+  lineno: number;
+  colno: number;
+}
+
+export interface Breadcrumb {
+  timestamp: number;
+  category: string;
+  message: string;
+  level: 'info';
+}
+
+export interface ExceptionValue {
+  type: string;
+  value: string;
+  stacktrace: { frames: StackFrame[] };
+}
+
+export interface SentryEvent {
+  event_id: string;
+  timestamp: number;
+  platform: 'javascript';
+  level: 'error';
+  environment: string;
+  release: string;
+  sdk: { name: string; version: string };
+  tags: Record<string, string>;
+  user?: { id: string };
+  contexts: { app_info: StateSnapshot };
+  fingerprint: string[];
+  exception: { values: ExceptionValue[] };
+  breadcrumbs: { values: Breadcrumb[] };
+}
+
+export interface ParsedDsn {
+  dsn: string;
+  endpoint: string;
+}
+
+const MAX_FRAMES = 50;
+const DSN_PATTERN = /^(https?):\/\/([^:@/]+)(?::[^@/]*)?@([^/]+)\/(?:.+\/)?(\d+)$/;
+const V8_FRAME = /^\s*at (?:(.+?) \()?(?:address at )?(.+?):(\d+):(\d+)\)?\s*$/;
+const JSC_FRAME = /^(?:(.*?)@)?(.+?):(\d+):(\d+)\s*$/;
+
+export function parseDsn(dsn: string): ParsedDsn | null {
+  const match = DSN_PATTERN.exec(dsn);
+  const protocol = match?.[1];
+  const publicKey = match?.[2];
+  const host = match?.[3];
+  const projectId = match?.[4];
+  if (protocol === undefined || publicKey === undefined || host === undefined || projectId === undefined) {
+    return null;
+  }
+  return { dsn, endpoint: `${protocol}://${host}/api/${projectId}/envelope/?sentry_key=${publicKey}&sentry_version=7` };
+}
+
+export function parseStack(stack: string | undefined): StackFrame[] {
+  const frames: StackFrame[] = [];
+  for (const line of (stack ?? '').split('\n')) {
+    const match = V8_FRAME.exec(line) ?? JSC_FRAME.exec(line);
+    const filename = match?.[2];
+    const lineno = match?.[3];
+    const colno = match?.[4];
+    if (filename === undefined || lineno === undefined || colno === undefined) {
+      continue;
+    }
+    const name = match?.[1];
+    frames.push({ ...(name ? { function: name } : {}), filename, lineno: Number(lineno), colno: Number(colno) });
+  }
+  return frames.reverse().slice(-MAX_FRAMES);
+}
+
+export function serializeEnvelope(dsn: string, event: SentryEvent, sentAt: string): string {
+  return [
+    JSON.stringify({ event_id: event.event_id, dsn, sent_at: sentAt }),
+    JSON.stringify({ type: 'event' }),
+    JSON.stringify(event),
+  ].join('\n');
+}

package/src/telemetry/reporter.ts

@@ -0,0 +1,170 @@
+import { ApiRequestError, isIdentityRejection } from '../backend/errors.ts';
+import { type Breadcrumb, parseDsn, type ParsedDsn, parseStack, type SentryEvent, serializeEnvelope, type StateSnapshot } from './envelope.ts';
+import { scrubString } from './scrub.ts';
+
+const MAX_SENDS_PER_SESSION = 50;
+const MAX_BREADCRUMBS = 30;
+const NETWORK_FAILURE = /network request failed|failed to fetch|network error|timed out/i;
+
+export interface ReportIdentity {
+  sourceId: string | null;
+  sessionId: number | null;
+  userExternalId: string | null;
+}
+
+export interface ReporterOptions {
+  dsn: string;
+  environment: string;
+  release: string;
+  sdkVersion: string;
+  send: (url: string, body: string) => Promise<unknown>;
+  now: () => number;
+  randomHex: (length: number) => string;
+  appInfo: () => StateSnapshot;
+}
+
+function describe(value: unknown): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function toError(context: string, error: unknown): Error {
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(error === undefined ? context : `${context}: ${describe(error)}`);
+}
+
+function fingerprintOf(context: string, error: Error): string[] {
+  if (error instanceof ApiRequestError) {
+    return ['api-request-error', error.endpoint, String(error.status), error.code ?? ''];
+  }
+  return [context, error.name];
+}
+
+function isNonActionable(error: unknown): error is Error {
+  if (error instanceof ApiRequestError) {
+    return error.kind !== 'http' || isIdentityRejection(error);
+  }
+  return error instanceof Error && NETWORK_FAILURE.test(error.message);
+}
+
+export class Reporter {
+  private readonly target: ParsedDsn | null;
+
+  private readonly breadcrumbs: Breadcrumb[] = [];
+
+  private publishableKey: string | null = null;
+
+  private identityProvider: (() => ReportIdentity) | null = null;
+
+  private sent = 0;
+
+  private reporting = false;
+
+  constructor(private readonly options: ReporterOptions) {
+    this.target = parseDsn(options.dsn);
+  }
+
+  setPublishableKey(publishableKey: string): void {
+    this.publishableKey = publishableKey;
+  }
+
+  setIdentityProvider(provider: () => ReportIdentity): void {
+    this.identityProvider = provider;
+  }
+
+  addBreadcrumb(category: string, message: string): void {
+    try {
+      this.breadcrumbs.push({ timestamp: this.options.now() / 1000, category, message: scrubString(message), level: 'info' });
+      if (this.breadcrumbs.length > MAX_BREADCRUMBS) {
+        this.breadcrumbs.shift();
+      }
+    } catch {
+      return;
+    }
+  }
+
+  report(context: string, error?: unknown): void {
+    if (this.reporting) {
+      return;
+    }
+    this.reporting = true;
+    try {
+      if (isNonActionable(error)) {
+        this.addBreadcrumb(error instanceof ApiRequestError ? 'api' : 'network', `${context}: ${error.message}`);
+      } else {
+        this.capture(context, toError(context, error));
+      }
+    } catch {
+      return;
+    } finally {
+      this.reporting = false;
+    }
+  }
+
+  private capture(context: string, error: Error): void {
+    if (this.target === null || this.sent >= MAX_SENDS_PER_SESSION) {
+      return;
+    }
+    this.sent += 1;
+    const { options } = this;
+    const appInfo = options.appInfo();
+    const identity = this.readIdentity();
+    const sessionId = identity?.sessionId ?? null;
+    const event: SentryEvent = {
+      event_id: options.randomHex(32),
+      timestamp: options.now() / 1000,
+      platform: 'javascript',
+      level: 'error',
+      environment: options.environment,
+      release: options.release,
+      sdk: { name: 'blar.react-native', version: options.sdkVersion },
+      tags: {
+        context: scrubString(context),
+        sdkVersion: options.sdkVersion,
+        publishableKey: this.publishableKey ?? 'unknown',
+        sourceId: identity?.sourceId ?? 'unknown',
+        sessionId: sessionId !== null ? String(sessionId) : 'none',
+        os: String(appInfo.os ?? 'unknown'),
+      },
+      ...(identity?.userExternalId ? { user: { id: identity.userExternalId } } : {}),
+      contexts: { app_info: appInfo },
+      fingerprint: fingerprintOf(context, error),
+      exception: {
+        values: [
+          {
+            type: error.name,
+            value: scrubString(error.message),
+            stacktrace: { frames: parseStack(error.stack).map((frame) => ({ ...frame, filename: scrubString(frame.filename) })) },
+          },
+        ],
+      },
+      breadcrumbs: { values: [...this.breadcrumbs] },
+    };
+    this.deliver(this.target, event);
+  }
+
+  private readIdentity(): ReportIdentity | null {
+    try {
+      return this.identityProvider?.() ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  private deliver(target: ParsedDsn, event: SentryEvent): void {
+    const body = serializeEnvelope(target.dsn, event, new Date(this.options.now()).toISOString());
+    try {
+      this.options.send(target.endpoint, body).catch(() => undefined);
+    } catch {
+      return;
+    }
+  }
+}

package/src/telemetry/scrub.ts

@@ -0,0 +1,10 @@
+const EMAIL_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+const JWT_PATTERN = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*/g;
+const BEARER_PATTERN = /\bBearer\s+[A-Za-z0-9._-]+/gi;
+
+export function scrubString(value: string): string {
+  return value
+    .replace(EMAIL_PATTERN, '[redacted-email]')
+    .replace(JWT_PATTERN, '[redacted-token]')
+    .replace(BEARER_PATTERN, 'Bearer [redacted]');
+}

package/src/telemetry/sdk-reporter.ts

@@ -0,0 +1,37 @@
+import { readAppInfo } from '../backend/app-info.ts';
+import { SDK_VERSION } from '../version.ts';
+import { SENTRY_DSN, SENTRY_ENVIRONMENT } from './build-info.generated.ts';
+import { Reporter, type ReportIdentity } from './reporter.ts';
+
+const HEX_DIGITS = 16;
+
+function randomHex(length: number): string {
+  return Array.from({ length }, () => Math.floor(Math.random() * HEX_DIGITS).toString(HEX_DIGITS)).join('');
+}
+
+const reporter = new Reporter({
+  dsn: SENTRY_DSN,
+  environment: SENTRY_ENVIRONMENT,
+  release: `blario-react-native@${SDK_VERSION}`,
+  sdkVersion: SDK_VERSION,
+  send: (url, body) => fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/x-sentry-envelope' }, body }),
+  now: Date.now,
+  randomHex,
+  appInfo: () => ({ ...readAppInfo() }),
+});
+
+export function reportSdkError(context: string, error?: unknown): void {
+  reporter.report(context, error);
+}
+
+export function recordSdkBreadcrumb(category: string, message: string): void {
+  reporter.addBreadcrumb(category, message);
+}
+
+export function setReportPublishableKey(publishableKey: string): void {
+  reporter.setPublishableKey(publishableKey);
+}
+
+export function setReportIdentityProvider(provider: () => ReportIdentity): void {
+  reporter.setIdentityProvider(provider);
+}

package/src/transport/connection-options.ts

@@ -0,0 +1,65 @@
+export interface ConnectionOptions {
+  publishableKey?: unknown;
+  apiBaseUrl?: unknown;
+  relayUrl?: unknown;
+}
+
+export type ConnectionConfig =
+  | { kind: 'backend'; publishableKey: string; apiBaseUrl: string }
+  | { kind: 'relay'; relayUrl: string }
+  | { kind: 'disabled' };
+
+function validHost(host: string): boolean {
+  if (host.startsWith('[')) {
+    const address = host.slice(1, -1);
+    const halves = address.split('::');
+    const groups = halves.flatMap((half) => half === '' ? [] : half.split(':'));
+    return halves.length <= 2 && groups.every((group) => /^[a-f0-9]{1,4}$/i.test(group)) &&
+      (halves.length === 2 ? groups.length < 8 : groups.length === 8);
+  }
+  if (/^[0-9.]+$/.test(host)) {
+    const octets = host.split('.');
+    return octets.length === 4 && octets.every((octet) => /^\d{1,3}$/.test(octet) && Number(octet) <= 255);
+  }
+  return host.replace(/\.$/, '').split('.').every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(label));
+}
+
+function normalizeUrl(value: unknown, socket: boolean): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const match = /^([a-z]+):\/\/(\[[a-f0-9:]+\]|[a-z0-9.-]+)(?::([0-9]{1,5}))?((?:\/[^?#]*)?)(\?[^#]*)?$/i.exec(value.trim());
+  if (match === null) {
+    return null;
+  }
+  const [, scheme = '', host = '', port, path = '', query = ''] = match;
+  const protocol = scheme.toLowerCase();
+  const allowed = socket ? ['ws', 'wss'] : ['http', 'https'];
+  const suffix = path + query;
+  if (!allowed.includes(protocol) || !validHost(host) ||
+      (port !== undefined && (Number(port) < 1 || Number(port) > 65535)) ||
+      (!socket && query !== '') || !/^[a-z0-9\-._~!$&'()*+,;=:@/%?]*$/i.test(suffix) || /%(?![a-f0-9]{2})/i.test(suffix)) {
+    return null;
+  }
+  return `${protocol}://${host.toLowerCase()}${port === undefined ? '' : `:${Number(port)}`}${socket ? suffix : path.replace(/\/+$/, '')}`;
+}
+
+export function normalizeApiBaseUrl(value: unknown): string | null {
+  return normalizeUrl(value, false);
+}
+
+export function normalizeRelayUrl(value: unknown): string | null {
+  return normalizeUrl(value, true);
+}
+
+export function resolveConnectionOptions(options: ConnectionOptions, development: boolean): ConnectionConfig {
+  const { publishableKey, apiBaseUrl, relayUrl } = options;
+  if (publishableKey !== undefined || apiBaseUrl !== undefined) {
+    const base = normalizeApiBaseUrl(apiBaseUrl);
+    return typeof publishableKey === 'string' && publishableKey === publishableKey.trim() && /^[\x21-\x7e]+$/.test(publishableKey) && base !== null
+      ? { kind: 'backend', publishableKey, apiBaseUrl: base }
+      : { kind: 'disabled' };
+  }
+  const relay = normalizeRelayUrl(relayUrl === undefined && development ? 'ws://localhost:8790' : relayUrl);
+  return relay === null ? { kind: 'disabled' } : { kind: 'relay', relayUrl: relay };
+}