@logbrew/react-native 0.1.0 → 0.1.2

package/lifecycle.cjs

@@ -0,0 +1,129 @@
+"use strict";
+
+const { SdkError } = require("@logbrew/sdk");
+const {
+  createReactNativeSpanAttributes,
+  createReactNativeTraceContext,
+  getActiveLogBrewTrace,
+  getReactNativeContext
+} = require("./index.cjs");
+
+function createReactNativeLifecycleSpanEvent({
+  durationMs, fromState, id, idFactory = defaultLifecycleSpanEventId, metadata = {}, name,
+  now = () => new Date().toISOString(), platform, appState, screen, sessionId, state, status = "ok",
+  timestamp, toState, trace
+} = {}) {
+  const safeFromState = normalizeLifecycleState(fromState);
+  const safeToState = normalizeLifecycleState(toState ?? state);
+  const transition = [safeFromState, safeToState].filter(Boolean).join("->");
+  const spanName = name ?? `app_state:${transition || safeToState || safeFromState || "change"}`;
+  const activeTrace = trace ?? getActiveLogBrewTrace() ?? createReactNativeTraceContext();
+  return {
+    id: id ?? idFactory({ fromState: safeFromState, screen, toState: safeToState }),
+    timestamp: timestamp ?? now(),
+    attributes: createReactNativeSpanAttributes({
+      name: spanName,
+      status,
+      durationMs,
+      trace: activeTrace,
+      metadata: {
+        ...getReactNativeContext({ platform, appState }),
+        source: "react-native.lifecycle",
+        appState: safeToState,
+        durationMs,
+        fromAppState: safeFromState,
+        screen,
+        sessionId,
+        toAppState: safeToState,
+        ...metadata
+      }
+    })
+  };
+}
+
+function captureReactNativeLifecycleSpan(client, input = {}) {
+  requireClient(client);
+  const event = createReactNativeLifecycleSpanEvent(input);
+  client.span(event.id, event.timestamp, event.attributes);
+  return event;
+}
+
+function createAppStateLifecycleSpanListener(client, appState, {
+  captureInitialState = false, metadata = {}, now = () => new Date().toISOString(), nowMs = () => Date.now(),
+  onError, platform, screen, sessionId, trace
+} = {}) {
+  requireClient(client);
+  if (!appState || typeof appState.addEventListener !== "function") {
+    throw new SdkError("configuration_error", "createAppStateLifecycleSpanListener requires AppState.addEventListener");
+  }
+
+  let previousState = normalizeLifecycleState(appState.currentState);
+  let previousChangedAtMs = nowMs();
+  if (captureInitialState && previousState !== undefined) {
+    captureReactNativeLifecycleSpan(client, {
+      appState, metadata, now, platform, screen, sessionId, toState: previousState, trace
+    });
+  }
+
+  const subscription = appState.addEventListener("change", (nextState) => {
+    try {
+      const safeNextState = normalizeLifecycleState(nextState);
+      if (safeNextState === undefined) {
+        return;
+      }
+      const changedAtMs = nowMs();
+      const durationMs = previousState === undefined ? undefined : Math.max(0, changedAtMs - previousChangedAtMs);
+      captureReactNativeLifecycleSpan(client, {
+        appState, durationMs, fromState: previousState, metadata, now, platform, screen, sessionId,
+        timestamp: now(), toState: safeNextState, trace
+      });
+      previousState = safeNextState;
+      previousChangedAtMs = changedAtMs;
+    } catch (error) {
+      if (typeof onError === "function") {
+        onError(error);
+      } else {
+        throw error;
+      }
+    }
+  });
+
+  return subscriptionRemover(subscription);
+}
+
+function requireClient(client) {
+  if (!client) {
+    throw new SdkError("configuration_error", "LogBrew React Native lifecycle helpers require a client");
+  }
+}
+
+function defaultLifecycleSpanEventId({ fromState, screen, toState }) {
+  return `evt_native_lifecycle_${slugify([screen, fromState, toState].filter(Boolean).join("_") || "app_state")}`;
+}
+
+function normalizeLifecycleState(state) {
+  return typeof state === "string" && state.trim() !== "" ? state.trim() : undefined;
+}
+
+function subscriptionRemover(subscription) {
+  if (typeof subscription === "function") {
+    return subscription;
+  }
+  if (subscription && typeof subscription.remove === "function") {
+    return () => subscription.remove();
+  }
+  return () => {};
+}
+
+function slugify(value) {
+  return String(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "") || "event";
+}
+
+module.exports = {
+  captureReactNativeLifecycleSpan,
+  createAppStateLifecycleSpanListener,
+  createReactNativeLifecycleSpanEvent
+};

package/lifecycle.d.cts

@@ -0,0 +1,50 @@
+import type { LogBrewClient, Metadata, SpanAttributes } from "@logbrew/sdk";
+import type {
+  ReactNativeAppStateLike,
+  ReactNativeContextOptions,
+  ReactNativeSpanEvent
+} from "./index.cjs";
+
+export type ReactNativeLifecycleSpanInput = ReactNativeContextOptions & {
+  durationMs?: number;
+  fromState?: string;
+  id?: string;
+  idFactory?: (context: ReactNativeLifecycleSpanIdFactoryContext) => string;
+  name?: string;
+  now?: () => string;
+  screen?: string;
+  sessionId?: string;
+  state?: string;
+  status?: SpanAttributes["status"];
+  timestamp?: string;
+  toState?: string;
+};
+
+export type ReactNativeLifecycleSpanIdFactoryContext = {
+  fromState?: string;
+  screen?: string;
+  toState?: string;
+};
+
+export type AppStateLifecycleSpanListenerOptions = ReactNativeContextOptions & {
+  captureInitialState?: boolean;
+  metadata?: Metadata;
+  now?: () => string;
+  nowMs?: () => number;
+  onError?: (error: unknown) => void;
+  screen?: string;
+  sessionId?: string;
+};
+
+export declare function createReactNativeLifecycleSpanEvent(
+  input?: ReactNativeLifecycleSpanInput
+): ReactNativeSpanEvent;
+export declare function captureReactNativeLifecycleSpan(
+  client: LogBrewClient,
+  input?: ReactNativeLifecycleSpanInput
+): ReactNativeSpanEvent;
+export declare function createAppStateLifecycleSpanListener(
+  client: LogBrewClient,
+  appState: ReactNativeAppStateLike,
+  options?: AppStateLifecycleSpanListenerOptions
+): () => void;

package/lifecycle.d.ts

@@ -0,0 +1,50 @@
+import type { LogBrewClient, Metadata, SpanAttributes } from "@logbrew/sdk";
+import type {
+  ReactNativeAppStateLike,
+  ReactNativeContextOptions,
+  ReactNativeSpanEvent
+} from "./index.js";
+
+export type ReactNativeLifecycleSpanInput = ReactNativeContextOptions & {
+  durationMs?: number;
+  fromState?: string;
+  id?: string;
+  idFactory?: (context: ReactNativeLifecycleSpanIdFactoryContext) => string;
+  name?: string;
+  now?: () => string;
+  screen?: string;
+  sessionId?: string;
+  state?: string;
+  status?: SpanAttributes["status"];
+  timestamp?: string;
+  toState?: string;
+};
+
+export type ReactNativeLifecycleSpanIdFactoryContext = {
+  fromState?: string;
+  screen?: string;
+  toState?: string;
+};
+
+export type AppStateLifecycleSpanListenerOptions = ReactNativeContextOptions & {
+  captureInitialState?: boolean;
+  metadata?: Metadata;
+  now?: () => string;
+  nowMs?: () => number;
+  onError?: (error: unknown) => void;
+  screen?: string;
+  sessionId?: string;
+};
+
+export declare function createReactNativeLifecycleSpanEvent(
+  input?: ReactNativeLifecycleSpanInput
+): ReactNativeSpanEvent;
+export declare function captureReactNativeLifecycleSpan(
+  client: LogBrewClient,
+  input?: ReactNativeLifecycleSpanInput
+): ReactNativeSpanEvent;
+export declare function createAppStateLifecycleSpanListener(
+  client: LogBrewClient,
+  appState: ReactNativeAppStateLike,
+  options?: AppStateLifecycleSpanListenerOptions
+): () => void;

package/lifecycle.js

@@ -0,0 +1,121 @@
+import { SdkError } from "@logbrew/sdk";
+import {
+  createReactNativeSpanAttributes,
+  createReactNativeTraceContext,
+  getActiveLogBrewTrace,
+  getReactNativeContext
+} from "./index.js";
+
+export function createReactNativeLifecycleSpanEvent({
+  durationMs, fromState, id, idFactory = defaultLifecycleSpanEventId, metadata = {}, name,
+  now = () => new Date().toISOString(), platform, appState, screen, sessionId, state, status = "ok",
+  timestamp, toState, trace
+} = {}) {
+  const safeFromState = normalizeLifecycleState(fromState);
+  const safeToState = normalizeLifecycleState(toState ?? state);
+  const transition = [safeFromState, safeToState].filter(Boolean).join("->");
+  const spanName = name ?? `app_state:${transition || safeToState || safeFromState || "change"}`;
+  const activeTrace = trace ?? getActiveLogBrewTrace() ?? createReactNativeTraceContext();
+  return {
+    id: id ?? idFactory({ fromState: safeFromState, screen, toState: safeToState }),
+    timestamp: timestamp ?? now(),
+    attributes: createReactNativeSpanAttributes({
+      name: spanName,
+      status,
+      durationMs,
+      trace: activeTrace,
+      metadata: {
+        ...getReactNativeContext({ platform, appState }),
+        source: "react-native.lifecycle",
+        appState: safeToState,
+        durationMs,
+        fromAppState: safeFromState,
+        screen,
+        sessionId,
+        toAppState: safeToState,
+        ...metadata
+      }
+    })
+  };
+}
+
+export function captureReactNativeLifecycleSpan(client, input = {}) {
+  requireClient(client);
+  const event = createReactNativeLifecycleSpanEvent(input);
+  client.span(event.id, event.timestamp, event.attributes);
+  return event;
+}
+
+export function createAppStateLifecycleSpanListener(client, appState, {
+  captureInitialState = false, metadata = {}, now = () => new Date().toISOString(), nowMs = () => Date.now(),
+  onError, platform, screen, sessionId, trace
+} = {}) {
+  requireClient(client);
+  if (!appState || typeof appState.addEventListener !== "function") {
+    throw new SdkError("configuration_error", "createAppStateLifecycleSpanListener requires AppState.addEventListener");
+  }
+
+  let previousState = normalizeLifecycleState(appState.currentState);
+  let previousChangedAtMs = nowMs();
+  if (captureInitialState && previousState !== undefined) {
+    captureReactNativeLifecycleSpan(client, {
+      appState, metadata, now, platform, screen, sessionId, toState: previousState, trace
+    });
+  }
+
+  const subscription = appState.addEventListener("change", (nextState) => {
+    try {
+      const safeNextState = normalizeLifecycleState(nextState);
+      if (safeNextState === undefined) {
+        return;
+      }
+      const changedAtMs = nowMs();
+      const durationMs = previousState === undefined ? undefined : Math.max(0, changedAtMs - previousChangedAtMs);
+      captureReactNativeLifecycleSpan(client, {
+        appState, durationMs, fromState: previousState, metadata, now, platform, screen, sessionId,
+        timestamp: now(), toState: safeNextState, trace
+      });
+      previousState = safeNextState;
+      previousChangedAtMs = changedAtMs;
+    } catch (error) {
+      if (typeof onError === "function") {
+        onError(error);
+      } else {
+        throw error;
+      }
+    }
+  });
+
+  return subscriptionRemover(subscription);
+}
+
+function requireClient(client) {
+  if (!client) {
+    throw new SdkError("configuration_error", "LogBrew React Native lifecycle helpers require a client");
+  }
+}
+
+function defaultLifecycleSpanEventId({ fromState, screen, toState }) {
+  return `evt_native_lifecycle_${slugify([screen, fromState, toState].filter(Boolean).join("_") || "app_state")}`;
+}
+
+function normalizeLifecycleState(state) {
+  return typeof state === "string" && state.trim() !== "" ? state.trim() : undefined;
+}
+
+function subscriptionRemover(subscription) {
+  if (typeof subscription === "function") {
+    return subscription;
+  }
+  if (subscription && typeof subscription.remove === "function") {
+    return () => subscription.remove();
+  }
+  return () => {};
+}
+
+function slugify(value) {
+  return String(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "") || "event";
+}

package/metadata.cjs

@@ -0,0 +1,175 @@
+"use strict";
+
+const SENSITIVE_METADATA_FACTORY_KEY_RE = new RegExp([
+  "body",
+  "payload",
+  "variable",
+  "header",
+  "authorization",
+  "cookie",
+  "to\u006ben",
+  "sec\u0072et",
+  "pass\u0077ord"
+].join("|"), "u");
+const REACT_NATIVE_DEBUG_ID_REGISTRY = Symbol.for("@logbrew/react-native/debug-ids");
+const SAFE_RELEASE_ARTIFACT_DEBUG_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const MAX_REACT_NATIVE_DEBUG_ID_REGISTRY_ENTRIES = 64;
+const MAX_REACT_NATIVE_DEBUG_ID_REGISTRY_FRAMES = 128;
+
+function createSafeReactNativeMetadata(metadata, metadataFactory, context) {
+  if (typeof metadataFactory !== "function") {
+    return metadata;
+  }
+  return {
+    ...metadata,
+    ...safeReactNativeMetadataFactoryResult(metadataFactory(context))
+  };
+}
+
+function safeReactNativeMetadataFactoryResult(candidate) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+    return {};
+  }
+  const metadata = {};
+  for (const [key, value] of Object.entries(candidate)) {
+    if (isSensitiveMetadataKey(key)) {
+      continue;
+    }
+    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      metadata[key] = value;
+    }
+  }
+  return metadata;
+}
+
+function sanitizeReactNativeIssueMetadata(metadata, compactMetadata) {
+  const next = { ...metadata };
+  for (const key of ["errorFrameFile", "releaseArtifactCodeFile"]) {
+    const path = reactNativeCodePath(next[key]);
+    if (path) {
+      next[key] = path;
+    }
+  }
+  const match = typeof next.issueGroupingKey === "string" ? next.issueGroupingKey.match(/^([^:]+):([^:]+):(.+)$/u) : null;
+  const path = match ? reactNativeCodePath(match[3]) : undefined;
+  if (path) {
+    next.issueGroupingKey = `${match[1]}:${match[2]}:${path}`;
+  }
+  return compactMetadata(next);
+}
+
+function sanitizeReactNativeIssueStackFrames(stackFrames) {
+  if (!Array.isArray(stackFrames)) {
+    return undefined;
+  }
+  return stackFrames.map((frame) => ({
+    ...frame,
+    filename: reactNativeCodePath(frame.filename) ?? frame.filename
+  }));
+}
+
+function runtimeReactNativeDebugIdMap() {
+  try {
+    const registry = globalThis?.[REACT_NATIVE_DEBUG_ID_REGISTRY];
+    if (!registry || Array.isArray(registry) || typeof registry !== "object") {
+      return undefined;
+    }
+    const entries = Object.entries(registry);
+    if (entries.length === 0 || entries.length > MAX_REACT_NATIVE_DEBUG_ID_REGISTRY_ENTRIES) {
+      return undefined;
+    }
+    const debugIdMap = Object.create(null);
+    let frameCount = 0;
+    for (const [stack, debugId] of entries) {
+      if (typeof debugId !== "string" || !SAFE_RELEASE_ARTIFACT_DEBUG_ID.test(debugId)) {
+        return undefined;
+      }
+      const normalizedDebugId = debugId.toLowerCase();
+      let stackFrameCount = 0;
+      for (const line of stack.split(/\r?\n/u)) {
+        const filename = runtimeStackFrameFilename(line);
+        if (!filename) {
+          continue;
+        }
+        frameCount += 1;
+        stackFrameCount += 1;
+        if (frameCount > MAX_REACT_NATIVE_DEBUG_ID_REGISTRY_FRAMES) {
+          return undefined;
+        }
+        const existingDebugId = debugIdMap[filename];
+        if (existingDebugId && existingDebugId !== normalizedDebugId) {
+          return undefined;
+        }
+        debugIdMap[filename] = normalizedDebugId;
+      }
+      if (stackFrameCount === 0) {
+        return undefined;
+      }
+    }
+    return frameCount > 0 ? debugIdMap : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isSensitiveMetadataKey(key) {
+  return SENSITIVE_METADATA_FACTORY_KEY_RE.test(String(key).toLowerCase());
+}
+
+function runtimeStackFrameFilename(rawLine) {
+  let location = typeof rawLine === "string" ? rawLine.trim() : "";
+  if (!location) {
+    return undefined;
+  }
+  if (location.startsWith("at ")) {
+    location = location.slice(3).trim();
+    if (location.endsWith(")") && location.includes("(")) {
+      location = location.slice(location.lastIndexOf("(") + 1, -1);
+    }
+  } else if (location.includes("@")) {
+    location = location.slice(location.lastIndexOf("@") + 1);
+  }
+  const parts = location.split(":");
+  if (parts.length < 3) {
+    return undefined;
+  }
+  const columnText = parts.pop();
+  const lineText = parts.pop();
+  const filename = parts.join(":").trim();
+  if (!/^[1-9]\d*$/u.test(lineText) || !/^[1-9]\d*$/u.test(columnText)) {
+    return undefined;
+  }
+  const line = Number(lineText);
+  const column = Number(columnText);
+  return Number.isSafeInteger(line) && Number.isSafeInteger(column) && filename ? filename : undefined;
+}
+
+function reactNativeCodePath(value) {
+  if (typeof value !== "string" || value.trim() === "") {
+    return undefined;
+  }
+  let path = value.trim();
+  const URLConstructor = globalThis.URL;
+  if (typeof URLConstructor === "function") {
+    try {
+      path = new URLConstructor(path).pathname || path;
+    } catch {
+      path = path.split(/[?#]/u, 1)[0].replace(/\\/g, "/");
+    }
+  } else {
+    path = path.split(/[?#]/u, 1)[0].replace(/\\/g, "/");
+  }
+  if (/^[A-Za-z]:\//u.test(path) || /^\/(?:Users|home|private|tmp|var)\//u.test(path)) {
+    path = path.replace(/\/+$/u, "");
+    return path.slice(path.lastIndexOf("/") + 1) || undefined;
+  }
+  return path || undefined;
+}
+
+module.exports = {
+  createSafeReactNativeMetadata,
+  runtimeReactNativeDebugIdMap,
+  safeReactNativeMetadataFactoryResult,
+  sanitizeReactNativeIssueMetadata,
+  sanitizeReactNativeIssueStackFrames
+};

package/metadata.js

@@ -0,0 +1,165 @@
+const SENSITIVE_METADATA_FACTORY_KEY_RE = new RegExp([
+  "body",
+  "payload",
+  "variable",
+  "header",
+  "authorization",
+  "cookie",
+  "to\u006ben",
+  "sec\u0072et",
+  "pass\u0077ord"
+].join("|"), "u");
+const REACT_NATIVE_DEBUG_ID_REGISTRY = Symbol.for("@logbrew/react-native/debug-ids");
+const SAFE_RELEASE_ARTIFACT_DEBUG_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const MAX_REACT_NATIVE_DEBUG_ID_REGISTRY_ENTRIES = 64;
+const MAX_REACT_NATIVE_DEBUG_ID_REGISTRY_FRAMES = 128;
+
+export function createSafeReactNativeMetadata(metadata, metadataFactory, context) {
+  if (typeof metadataFactory !== "function") {
+    return metadata;
+  }
+  return {
+    ...metadata,
+    ...safeReactNativeMetadataFactoryResult(metadataFactory(context))
+  };
+}
+
+export function safeReactNativeMetadataFactoryResult(candidate) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+    return {};
+  }
+  const metadata = {};
+  for (const [key, value] of Object.entries(candidate)) {
+    if (isSensitiveMetadataKey(key)) {
+      continue;
+    }
+    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      metadata[key] = value;
+    }
+  }
+  return metadata;
+}
+
+export function sanitizeReactNativeIssueMetadata(metadata, compactMetadata) {
+  const next = { ...metadata };
+  for (const key of ["errorFrameFile", "releaseArtifactCodeFile"]) {
+    const path = reactNativeCodePath(next[key]);
+    if (path) {
+      next[key] = path;
+    }
+  }
+  const match = typeof next.issueGroupingKey === "string" ? next.issueGroupingKey.match(/^([^:]+):([^:]+):(.+)$/u) : null;
+  const path = match ? reactNativeCodePath(match[3]) : undefined;
+  if (path) {
+    next.issueGroupingKey = `${match[1]}:${match[2]}:${path}`;
+  }
+  return compactMetadata(next);
+}
+
+export function sanitizeReactNativeIssueStackFrames(stackFrames) {
+  if (!Array.isArray(stackFrames)) {
+    return undefined;
+  }
+  return stackFrames.map((frame) => ({
+    ...frame,
+    filename: reactNativeCodePath(frame.filename) ?? frame.filename
+  }));
+}
+
+export function runtimeReactNativeDebugIdMap() {
+  try {
+    const registry = globalThis?.[REACT_NATIVE_DEBUG_ID_REGISTRY];
+    if (!registry || Array.isArray(registry) || typeof registry !== "object") {
+      return undefined;
+    }
+    const entries = Object.entries(registry);
+    if (entries.length === 0 || entries.length > MAX_REACT_NATIVE_DEBUG_ID_REGISTRY_ENTRIES) {
+      return undefined;
+    }
+    const debugIdMap = Object.create(null);
+    let frameCount = 0;
+    for (const [stack, debugId] of entries) {
+      if (typeof debugId !== "string" || !SAFE_RELEASE_ARTIFACT_DEBUG_ID.test(debugId)) {
+        return undefined;
+      }
+      const normalizedDebugId = debugId.toLowerCase();
+      let stackFrameCount = 0;
+      for (const line of stack.split(/\r?\n/u)) {
+        const filename = runtimeStackFrameFilename(line);
+        if (!filename) {
+          continue;
+        }
+        frameCount += 1;
+        stackFrameCount += 1;
+        if (frameCount > MAX_REACT_NATIVE_DEBUG_ID_REGISTRY_FRAMES) {
+          return undefined;
+        }
+        const existingDebugId = debugIdMap[filename];
+        if (existingDebugId && existingDebugId !== normalizedDebugId) {
+          return undefined;
+        }
+        debugIdMap[filename] = normalizedDebugId;
+      }
+      if (stackFrameCount === 0) {
+        return undefined;
+      }
+    }
+    return frameCount > 0 ? debugIdMap : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isSensitiveMetadataKey(key) {
+  return SENSITIVE_METADATA_FACTORY_KEY_RE.test(String(key).toLowerCase());
+}
+
+function runtimeStackFrameFilename(rawLine) {
+  let location = typeof rawLine === "string" ? rawLine.trim() : "";
+  if (!location) {
+    return undefined;
+  }
+  if (location.startsWith("at ")) {
+    location = location.slice(3).trim();
+    if (location.endsWith(")") && location.includes("(")) {
+      location = location.slice(location.lastIndexOf("(") + 1, -1);
+    }
+  } else if (location.includes("@")) {
+    location = location.slice(location.lastIndexOf("@") + 1);
+  }
+  const parts = location.split(":");
+  if (parts.length < 3) {
+    return undefined;
+  }
+  const columnText = parts.pop();
+  const lineText = parts.pop();
+  const filename = parts.join(":").trim();
+  if (!/^[1-9]\d*$/u.test(lineText) || !/^[1-9]\d*$/u.test(columnText)) {
+    return undefined;
+  }
+  const line = Number(lineText);
+  const column = Number(columnText);
+  return Number.isSafeInteger(line) && Number.isSafeInteger(column) && filename ? filename : undefined;
+}
+
+function reactNativeCodePath(value) {
+  if (typeof value !== "string" || value.trim() === "") {
+    return undefined;
+  }
+  let path = value.trim();
+  const URLConstructor = globalThis.URL;
+  if (typeof URLConstructor === "function") {
+    try {
+      path = new URLConstructor(path).pathname || path;
+    } catch {
+      path = path.split(/[?#]/u, 1)[0].replace(/\\/g, "/");
+    }
+  } else {
+    path = path.split(/[?#]/u, 1)[0].replace(/\\/g, "/");
+  }
+  if (/^[A-Za-z]:\//u.test(path) || /^\/(?:Users|home|private|tmp|var)\//u.test(path)) {
+    path = path.replace(/\/+$/u, "");
+    return path.slice(path.lastIndexOf("/") + 1) || undefined;
+  }
+  return path || undefined;
+}