@xmoxmo/bncr 0.5.6 → 0.5.8

package/src/messaging/outbound/reply-enqueue.ts

@@ -1,11 +1,34 @@
+import { buildBncrDebugJsonMessage } from '../../core/logging.ts';
 import type { BncrRoute, OutboxEntry } from '../../core/types.ts';
-import { extractConsumptionFields, parseBncrMarker } from './marker-parser.ts';
+import {
+  buildNormalizedSends,
+  type NormalizedOutboundSend,
+  normalizeOutboundSend,
+} from './normalize-outbound-send.ts';
 import { hasReplyMediaEntries } from './reply-enqueue-media.ts';
 import type { OutboundReplyTargetPolicy } from './reply-target-policy.ts';
 import { normalizeOutboundReplyToId } from './reply-target-policy.ts';
 
 const MEDIA_TEXT_SPLIT_THRESHOLD = 1020;
 
+type BuildOutboxEntryFn = (args: {
+  accountId: string;
+  sessionKey: string;
+  route: BncrRoute;
+  type?: string;
+  msg: string;
+  kind?: 'tool' | 'block' | 'final';
+  replyToId?: string;
+  replyTargetPolicy?: OutboundReplyTargetPolicy;
+  extra?: Record<string, unknown>;
+  transferMode?: 'text' | 'media';
+  mediaUrl?: string;
+  mediaLocalRoots?: readonly string[];
+  asVoice?: boolean;
+  audioAsVoice?: boolean;
+  downloadMedia?: boolean;
+}) => OutboxEntry;
+
 export type ReplyEnqueuePlan =
   | { kind: 'text-only' }
   | { kind: 'media-only'; clearText: false }
@@ -21,6 +44,7 @@ export type ReplyPayloadInput = {
   audioAsVoice?: boolean;
   downloadMedia?: boolean;
   type?: string;
+  markerHasMsg?: boolean;
   extra?: Record<string, unknown>;
   kind?: 'tool' | 'block' | 'final';
   replyToId?: string;
@@ -35,20 +59,13 @@ export type NormalizedReplyPayload = {
   audioAsVoice: boolean;
   downloadMedia?: boolean;
   type?: string;
+  markerHasMsg?: boolean;
   extra?: Record<string, unknown>;
   kind?: 'tool' | 'block' | 'final';
   replyToId: string;
   replyTargetPolicy: OutboundReplyTargetPolicy;
 };
 
-export type ReplyMediaEntriesParams = {
-  accountId: string;
-  sessionKey: string;
-  route: BncrRoute;
-  payload: NormalizedReplyPayload;
-  mediaLocalRoots?: readonly string[];
-};
-
 export type EnqueueNormalizedReplyPayloadParams = {
   accountId: string;
   sessionKey: string;
@@ -58,46 +75,7 @@ export type EnqueueNormalizedReplyPayloadParams = {
   replyToId?: string;
 };
 
-export type ReplyMediaFileTransferParams = {
-  accountId: string;
-  sessionKey: string;
-  route: BncrRoute;
-  mediaUrl: string;
-  mediaLocalRoots?: readonly string[];
-  text: string;
-  normalizedText: string;
-  asVoice: boolean;
-  audioAsVoice: boolean;
-  downloadMedia?: boolean;
-  type?: string;
-  extra?: Record<string, unknown>;
-  kind?: 'tool' | 'block' | 'final';
-  replyToId: string;
-  replyTargetPolicy: OutboundReplyTargetPolicy;
-  createdAt: number;
-};
-
-export type EnqueueSingleReplyMediaEntryParams = {
-  params: ReplyMediaEntriesParams;
-  mediaUrl: string;
-  normalizedText: string;
-  text: string;
-  fallback: { text: string; reason: string } | null;
-  currentTime: number;
-};
-
-export type ReplyMediaFallbackTextEntryParams = {
-  accountId: string;
-  sessionKey: string;
-  route: BncrRoute;
-  mediaUrl: string;
-  kind?: 'tool' | 'block' | 'final';
-  replyToId: string;
-  replyTargetPolicy: OutboundReplyTargetPolicy;
-  fallback: { text: string; reason: string };
-};
-
-export function shouldSplitReplyMediaText(payload: NormalizedReplyPayload) {
+function shouldSplitReplyMediaText(payload: NormalizedReplyPayload) {
   if (!payload.text) return false;
   if (payload.mediaList.length > 1) return true;
   return payload.text.length > MEDIA_TEXT_SPLIT_THRESHOLD;
@@ -115,87 +93,260 @@ export function buildReplyEnqueuePlan(payload: NormalizedReplyPayload): ReplyEnq
   return { kind: 'media-only', clearText: false };
 }
 
-export function withoutReplyMediaText(payload: NormalizedReplyPayload): NormalizedReplyPayload {
-  return {
-    ...payload,
-    text: '',
-  };
-}
-
-export function buildReplyTextOutboxEntry(
+/**
+ * @deprecated Only used by native-reply-delivery.test.mjs. Not called from production code.
+ */
+export function enqueueReplyTextEntry(
   params: {
     accountId: string;
     sessionKey: string;
     route: BncrRoute;
-    text: string;
-    kind?: 'tool' | 'block' | 'final';
-    replyToId: string;
-    replyTargetPolicy: OutboundReplyTargetPolicy;
-    extra?: Record<string, unknown>;
+    payload: NormalizedReplyPayload;
   },
   helpers: {
-    buildTextOutboxEntry: (args: {
+    enqueueOutbound: (entry: OutboxEntry) => void;
+    buildOutboxEntry: (args: {
       accountId: string;
       sessionKey: string;
       route: BncrRoute;
-      text: string;
+      type?: string;
+      msg: string;
       kind?: 'tool' | 'block' | 'final';
       replyToId?: string;
       replyTargetPolicy?: OutboundReplyTargetPolicy;
       extra?: Record<string, unknown>;
+      transferMode?: 'text' | 'media';
     }) => OutboxEntry;
   },
-): OutboxEntry {
-  return helpers.buildTextOutboxEntry({
-    accountId: params.accountId,
-    sessionKey: params.sessionKey,
-    route: params.route,
-    text: params.text,
-    kind: params.kind,
-    replyToId: params.replyToId || undefined,
-    replyTargetPolicy: params.replyTargetPolicy,
-    extra: params.extra,
-  });
+): void {
+  if (!params.payload.text && !params.payload.extra) return;
+
+  helpers.enqueueOutbound(
+    helpers.buildOutboxEntry({
+      accountId: params.accountId,
+      sessionKey: params.sessionKey,
+      route: params.route,
+      type: 'text',
+      msg: params.payload.text,
+      extra: params.payload.extra,
+      kind: params.payload.kind,
+      replyToId: params.payload.replyToId,
+      replyTargetPolicy: params.payload.replyTargetPolicy,
+    }),
+  );
 }
 
-export function enqueueReplyTextEntry(
-  params: {
-    accountId: string;
-    sessionKey: string;
-    route: BncrRoute;
-    payload: NormalizedReplyPayload;
+/**
+ * Dispatch all entries from the normalisation plan through a unified path.
+ *
+ * `buildNormalizedSends` returns one or more sends (pre-send text-only +
+ * main payload).  Every entry goes through `buildReplyEnqueuePlan` → the same
+ * text/media dispatch.  There is no separate pre-send or main-send branch.
+ */
+function buildSendPayload(
+  entry: NormalizedOutboundSend,
+  parent: NormalizedReplyPayload,
+): NormalizedReplyPayload {
+  return {
+    text: entry.text,
+    mediaUrl: entry.mediaUrl || '',
+    mediaUrls: entry.mediaUrls,
+    mediaList: entry.mediaUrl ? [entry.mediaUrl] : entry.mediaUrls?.length ? entry.mediaUrls : [],
+    asVoice: entry.asVoice,
+    audioAsVoice: entry.audioAsVoice,
+    downloadMedia: entry.downloadMedia,
+    type: entry.type,
+    extra: entry.extra,
+    kind: entry.kind,
+    replyToId: entry.replyToId ?? '',
+    replyTargetPolicy: parent.replyTargetPolicy,
+  };
+}
+
+/**
+ * Unified outbound dispatch: single exit point for all sends.
+ *
+ * Iterates `buildNormalizedSends` entries and dispatches each through
+ * the existing text or media helpers internally.  External callers only
+ * see one unified function — they do not choose the branch.
+ */
+function enqueueUnifiedOutbound(
+  params: EnqueueNormalizedReplyPayloadParams,
+  helpers: {
+    enqueueOutbound: (entry: OutboxEntry) => void;
+    buildOutboxEntry: BuildOutboxEntryFn;
+    tryBuildMediaDedupeFallback: (args: {
+      sessionKey: string;
+      mediaUrl: string;
+      text: string;
+      replyToId: string;
+      currentTime: number;
+    }) => {
+      text: string;
+      reason: 'same-text-sent-checkmark' | 'text-changed-downgrade';
+    } | null;
+    rememberRecentMediaSend: (args: {
+      sessionKey: string;
+      mediaUrl: string;
+      text: string;
+      replyToId: string;
+      createdAt: number;
+    }) => void;
+    logInfo: (
+      scope: string | undefined,
+      message: string,
+      options?: { debugOnly?: boolean },
+    ) => void;
   },
+): void {
+  for (const entry of buildNormalizedSends(params.payload)) {
+    const sendPayload = buildSendPayload(entry, params.payload);
+    const plan = buildReplyEnqueuePlan(sendPayload);
+
+    if (plan.kind === 'text-and-media') {
+      // Text first, then media entries with empty text
+      helpers.enqueueOutbound(
+        helpers.buildOutboxEntry({
+          accountId: params.accountId,
+          sessionKey: params.sessionKey,
+          route: params.route,
+          type: 'text',
+          msg: sendPayload.text,
+          kind: sendPayload.kind,
+          replyToId: sendPayload.replyToId || undefined,
+          replyTargetPolicy: sendPayload.replyTargetPolicy,
+          extra: sendPayload.extra,
+        }),
+      );
+      enqueueUnifiedMediaEntries(params, sendPayload, '', helpers);
+      continue;
+    }
+
+    if (plan.kind !== 'text-only') {
+      // Media-only: first entry carries caption text
+      enqueueUnifiedMediaEntries(params, sendPayload, sendPayload.text, helpers);
+      continue;
+    }
+
+    // Text-only
+    if (!sendPayload.text && !sendPayload.extra) continue;
+    helpers.enqueueOutbound(
+      helpers.buildOutboxEntry({
+        accountId: params.accountId,
+        sessionKey: params.sessionKey,
+        route: params.route,
+        type: 'text',
+        msg: sendPayload.text,
+        kind: sendPayload.kind,
+        replyToId: sendPayload.replyToId || undefined,
+        replyTargetPolicy: sendPayload.replyTargetPolicy,
+        extra: sendPayload.extra,
+      }),
+    );
+  }
+}
+
+/** Internal: iterate mediaList and enqueue file-transfer entries (with dedup). */
+function enqueueUnifiedMediaEntries(
+  params: EnqueueNormalizedReplyPayloadParams,
+  sendPayload: NormalizedReplyPayload,
+  firstCaption: string,
   helpers: {
     enqueueOutbound: (entry: OutboxEntry) => void;
-    buildTextOutboxEntry: (args: {
-      accountId: string;
+    buildOutboxEntry: BuildOutboxEntryFn;
+    tryBuildMediaDedupeFallback: (args: {
       sessionKey: string;
-      route: BncrRoute;
+      mediaUrl: string;
       text: string;
-      kind?: 'tool' | 'block' | 'final';
-      replyToId?: string;
-      replyTargetPolicy?: OutboundReplyTargetPolicy;
-      extra?: Record<string, unknown>;
-    }) => OutboxEntry;
+      replyToId: string;
+      currentTime: number;
+    }) => {
+      text: string;
+      reason: 'same-text-sent-checkmark' | 'text-changed-downgrade';
+    } | null;
+    rememberRecentMediaSend: (args: {
+      sessionKey: string;
+      mediaUrl: string;
+      text: string;
+      replyToId: string;
+      createdAt: number;
+    }) => void;
+    logInfo: (
+      scope: string | undefined,
+      message: string,
+      options?: { debugOnly?: boolean },
+    ) => void;
   },
 ): void {
-  if (!params.payload.text && !params.payload.extra) return;
+  let first = true;
+  for (const mediaUrl of sendPayload.mediaList) {
+    const text = first ? firstCaption : '';
+    const currentTime = Date.now();
+    const normalizedText = text || '';
+    const fallback = helpers.tryBuildMediaDedupeFallback({
+      sessionKey: params.sessionKey,
+      mediaUrl,
+      text: normalizedText,
+      replyToId: sendPayload.replyToId,
+      currentTime,
+    });
 
-  helpers.enqueueOutbound(
-    buildReplyTextOutboxEntry(
-      {
+    if (fallback) {
+      helpers.logInfo(
+        'outbound',
+        buildBncrDebugJsonMessage('media-dedupe-hit', {
+          sessionKey: params.sessionKey,
+          mediaUrl,
+          text: normalizedText,
+          replyToId: sendPayload.replyToId,
+          reason: fallback.reason,
+        }),
+        { debugOnly: true },
+      );
+      helpers.enqueueOutbound(
+        helpers.buildOutboxEntry({
+          accountId: params.accountId,
+          sessionKey: params.sessionKey,
+          route: params.route,
+          type: 'text',
+          msg: fallback.text,
+          kind: sendPayload.kind,
+          replyToId: sendPayload.replyToId || undefined,
+          replyTargetPolicy: sendPayload.replyTargetPolicy,
+        }),
+      );
+      first = false;
+      continue;
+    }
+
+    helpers.enqueueOutbound(
+      helpers.buildOutboxEntry({
         accountId: params.accountId,
         sessionKey: params.sessionKey,
         route: params.route,
-        text: params.payload.text,
-        extra: params.payload.extra,
-        kind: params.payload.kind,
-        replyToId: params.payload.replyToId,
-        replyTargetPolicy: params.payload.replyTargetPolicy,
-      },
-      { buildTextOutboxEntry: helpers.buildTextOutboxEntry },
-    ),
-  );
+        type: sendPayload.type,
+        msg: text,
+        kind: sendPayload.kind,
+        replyToId: sendPayload.replyToId,
+        replyTargetPolicy: sendPayload.replyTargetPolicy,
+        extra: sendPayload.extra,
+        transferMode: 'media',
+        mediaUrl,
+        mediaLocalRoots: params.mediaLocalRoots,
+        asVoice: sendPayload.asVoice,
+        audioAsVoice: sendPayload.audioAsVoice,
+        downloadMedia: sendPayload.downloadMedia,
+      }),
+    );
+    helpers.rememberRecentMediaSend({
+      sessionKey: params.sessionKey,
+      mediaUrl,
+      text: normalizedText,
+      replyToId: sendPayload.replyToId,
+      createdAt: currentTime,
+    });
+    first = false;
+  }
 }
 
 export function enqueueNormalizedReplyPayload(
@@ -207,15 +358,33 @@ export function enqueueNormalizedReplyPayload(
       route: BncrRoute;
       payload: NormalizedReplyPayload;
     }) => void;
-    enqueueReplyMediaEntries: (params: ReplyMediaEntriesParams) => void;
-    enqueueReplyTextEntry: (params: {
-      accountId: string;
+    enqueueOutbound: (entry: OutboxEntry) => void;
+    buildOutboxEntry: BuildOutboxEntryFn;
+    tryBuildMediaDedupeFallback: (args: {
       sessionKey: string;
-      route: BncrRoute;
-      payload: NormalizedReplyPayload;
+      mediaUrl: string;
+      text: string;
+      replyToId: string;
+      currentTime: number;
+    }) => {
+      text: string;
+      reason: 'same-text-sent-checkmark' | 'text-changed-downgrade';
+    } | null;
+    rememberRecentMediaSend: (args: {
+      sessionKey: string;
+      mediaUrl: string;
+      text: string;
+      replyToId: string;
+      createdAt: number;
     }) => void;
+    logInfo: (
+      scope: string | undefined,
+      message: string,
+      options?: { debugOnly?: boolean },
+    ) => void;
   },
 ): void {
+  // Log only the main (last) send entry for traceability.
   helpers.logEnqueueFromReply({
     accountId: params.accountId,
     sessionKey: params.sessionKey,
@@ -223,83 +392,52 @@ export function enqueueNormalizedReplyPayload(
     payload: params.payload,
   });
 
-  const plan = buildReplyEnqueuePlan(params.payload);
-
-  if (plan.kind === 'text-and-media') {
-    helpers.enqueueReplyTextEntry({
-      accountId: params.accountId,
-      sessionKey: params.sessionKey,
-      route: params.route,
-      payload: params.payload,
-    });
-    helpers.enqueueReplyMediaEntries({
-      accountId: params.accountId,
-      sessionKey: params.sessionKey,
-      route: params.route,
-      payload: withoutReplyMediaText(params.payload),
-      mediaLocalRoots: params.mediaLocalRoots,
-    });
-    return;
-  }
-
-  if (plan.kind !== 'text-only') {
-    helpers.enqueueReplyMediaEntries({
-      accountId: params.accountId,
-      sessionKey: params.sessionKey,
-      route: params.route,
-      payload: params.payload,
-      mediaLocalRoots: params.mediaLocalRoots,
-    });
-    return;
-  }
-
-  helpers.enqueueReplyTextEntry({
-    accountId: params.accountId,
-    sessionKey: params.sessionKey,
-    route: params.route,
-    payload: params.payload,
-  });
+  // Dispatch ALL entries (pre-send + main) through the same path.
+  enqueueUnifiedOutbound(params, helpers);
 }
 
-export function normalizeReplyPayload(
+export async function normalizeReplyPayload(
   payload: ReplyPayloadInput,
   helpers: { asString: (value: unknown, fallback?: string) => string },
   options?: { replyTargetPolicy?: OutboundReplyTargetPolicy },
-): NormalizedReplyPayload {
-  const rawText = helpers.asString(payload?.text || '').trim();
-  // Parse [BncrParam:...] marker from reply text
-  const { cleanText, params: markerParams } = parseBncrMarker(rawText);
-  const text = cleanText;
-  const mediaUrl = helpers.asString(payload?.mediaUrl || '').trim();
-  const mediaUrls = Array.isArray(payload?.mediaUrls)
-    ? payload.mediaUrls.map((v) => helpers.asString(v || '').trim()).filter(Boolean)
-    : undefined;
-  const type = helpers.asString(payload?.type || '').trim();
-  // Merge marker params with payload extra (marker wins), strip consumption fields
-  const mergedExtra: Record<string, unknown> = {
-    ...(payload?.extra ? { ...payload.extra } : {}),
-    ...markerParams,
-  };
-  const { remaining } = extractConsumptionFields(
-    Object.keys(mergedExtra).length > 0 ? mergedExtra : undefined,
-  );
-  const finalExtra = Object.keys(remaining).length > 0 ? remaining : undefined;
-  return {
-    text,
-    mediaUrl,
-    mediaUrls,
-    mediaList: mediaUrls?.length ? mediaUrls : mediaUrl ? [mediaUrl] : [],
+): Promise<NormalizedReplyPayload> {
+  const normalized = await normalizeOutboundSend({
+    text: helpers.asString(payload?.text || ''),
+    mediaUrl: helpers.asString(payload?.mediaUrl || ''),
+    mediaUrls: payload?.mediaUrls,
     asVoice: payload?.asVoice === true,
     audioAsVoice: payload?.audioAsVoice === true,
-    downloadMedia: payload?.downloadMedia === true ? true : undefined,
-    ...(type ? { type } : {}),
-    ...(finalExtra ? { extra: finalExtra } : {}),
+    downloadMedia: payload?.downloadMedia,
+    type: helpers.asString(payload?.type || '').trim() || undefined,
     kind: payload?.kind,
-    replyTargetPolicy: options?.replyTargetPolicy ?? 'agent-default',
+    replyToId: payload?.replyToId,
+    extra: payload?.extra,
+  });
+
+  const markerHasMsg = normalized.markerHasMsg === true;
+  const mediaUrl = helpers.asString(normalized.mediaUrl || '');
+  const mediaUrls = normalized.mediaUrls;
+  const mediaList = mediaUrls?.length ? mediaUrls : mediaUrl ? [mediaUrl] : [];
+  const kind = normalized.kind;
+  const replyTargetPolicy = options?.replyTargetPolicy ?? 'agent-default';
+
+  return {
+    text: normalized.text,
+    mediaUrl,
+    mediaUrls,
+    mediaList,
+    asVoice: normalized.asVoice,
+    audioAsVoice: normalized.audioAsVoice,
+    downloadMedia: normalized.downloadMedia,
+    ...(normalized.type ? { type: normalized.type } : {}),
+    ...(normalized.extra ? { extra: normalized.extra } : {}),
+    markerHasMsg,
+    kind,
+    replyTargetPolicy,
     replyToId: normalizeOutboundReplyToId({
-      kind: payload?.kind,
-      replyToId: payload?.replyToId,
-      replyTargetPolicy: options?.replyTargetPolicy,
+      kind,
+      replyToId: normalized.replyToId ?? payload?.replyToId,
+      replyTargetPolicy,
     }),
   };
 }

package/src/messaging/outbound/session-route.ts

@@ -7,6 +7,7 @@ import {
   routeScopeToHex,
 } from '../../core/targets.ts';
 import type { BncrRoute } from '../../core/types.ts';
+import { asString } from '../../core/value-sanitize.ts';
 import { buildOpenClawChannelOutboundSessionRoute } from '../../openclaw/session-route-runtime.ts';
 import type { BncrChannelConfigRoot } from '../../plugin/channel-runtime-types.ts';
 
@@ -18,7 +19,7 @@ type BncrChannelRouteRefFields = {
     rawTo: string;
     chatType: 'direct' | 'group';
   };
-  thread?: { id: string };
+  thread?: { id: string | number };
 };
 
 type BncrOutboundSessionRoute = ChannelOutboundSessionRoute & BncrChannelRouteRefFields;
@@ -30,24 +31,18 @@ type ResolveBncrOutboundSessionRouteParams = {
   accountId?: string;
   target: string;
   resolvedTarget?: { to?: string } | null;
-  threadId?: string;
+  threadId?: string | number | null;
   canonicalAgentId: string;
   resolveRouteBySession?: (raw: string, accountId: string) => BncrRoute | null;
 };
 
-function asString(v: unknown, fallback = ''): string {
-  if (typeof v === 'string') return v;
-  if (v == null) return fallback;
-  return String(v);
-}
-
 function attachBncrChannelRouteRefFields(args: {
   built: ChannelOutboundSessionRoute;
   channel: string;
   accountId?: string;
   to: string;
   chatType: 'direct' | 'group';
-  threadId?: string;
+  threadId?: string | number | null;
 }): BncrOutboundSessionRoute {
   const { built, channel, accountId, to, chatType, threadId } = args;
   return {
@@ -59,7 +54,7 @@ function attachBncrChannelRouteRefFields(args: {
       rawTo: to,
       chatType,
     },
-    ...(threadId !== undefined ? { thread: { id: threadId } } : {}),
+    ...(threadId != null ? { thread: { id: threadId } } : {}),
   };
 }
 
@@ -99,7 +94,7 @@ export function resolveBncrOutboundSessionRoute(params: ResolveBncrOutboundSessi
     chatType: 'direct',
     from: displayTo,
     to: displayTo,
-    ...(params.threadId !== undefined ? { threadId: params.threadId } : {}),
+    ...(params.threadId != null ? { threadId: params.threadId } : {}),
   });
 
   return attachBncrChannelRouteRefFields({

package/src/messaging/outbound/target-resolver.ts

@@ -4,6 +4,7 @@ import {
   parseStrictBncrSessionKey,
 } from '../../core/targets.ts';
 import type { BncrRoute } from '../../core/types.ts';
+import { asString } from '../../core/value-sanitize.ts';
 
 type ResolveBncrOutboundTargetParams = {
   target: string;
@@ -11,12 +12,6 @@ type ResolveBncrOutboundTargetParams = {
   resolveRouteBySession?: (raw: string, accountId: string) => BncrRoute | null;
 };
 
-function asString(v: unknown, fallback = ''): string {
-  if (typeof v === 'string') return v;
-  if (v == null) return fallback;
-  return String(v);
-}
-
 export function looksLikeBncrExplicitTarget(input: string): boolean {
   const raw = asString(input).trim();
   if (!raw) return false;

package/src/openclaw/media-runtime.ts

@@ -48,7 +48,7 @@ export function isOpenClawRemoteHttpMediaUrl(mediaUrl: string): boolean {
  * Returns the first absolute path that exists on disk, or the original
  * relative path if nothing is found (the host will then emit its own error).
  */
-export function resolveRelativeMediaPath(mediaUrl: string, localRoots?: readonly string[]): string {
+function resolveRelativeMediaPath(mediaUrl: string, localRoots?: readonly string[]): string {
   if (!mediaUrl || !localRoots?.length) return mediaUrl;
   if (path.isAbsolute(mediaUrl)) return mediaUrl;
   // HTTP / file:// / data: / ~ paths are handled elsewhere