@supersoniks/concorde 4.9.96 → 4.9.97-visual-stack.0

package/src/core/components/functional/webgpu/wgsl-prelude.ts

@@ -0,0 +1,81 @@
+/**
+ * Prelude WGSL pour `sonic-webgpu`.
+ * L’utilisateur fournit `fn mainImage(uv: vec2f, fragCoord: vec2f) -> vec4f`.
+ */
+
+export const DEFAULT_MAIN_IMAGE = `
+fn mainImage(uv: vec2f, fragCoord: vec2f) -> vec4f {
+  _ = fragCoord;
+  let c = iChannel0(uv);
+  if (c.a > 0.001 || c.r + c.g + c.b > 0.001) {
+    return c;
+  }
+  let g = 0.15 + 0.25 * uv.y;
+  return vec4f(g, g * 0.85 + 0.08 * u.params.x, 0.35 + 0.4 * uv.x, 1.0);
+}
+`.trim();
+
+const PRELUDE = `
+struct SonicUniforms {
+  resolution: vec2f,
+  time: f32,
+  frame: f32,
+  mouse: vec4f,
+  params: vec4f,
+}
+
+@group(0) @binding(0) var<uniform> u: SonicUniforms;
+@group(0) @binding(1) var channel0Tex: texture_2d<f32>;
+@group(0) @binding(2) var channel1Tex: texture_2d<f32>;
+@group(0) @binding(3) var channel2Tex: texture_2d<f32>;
+@group(0) @binding(4) var channel3Tex: texture_2d<f32>;
+@group(0) @binding(5) var texSampler: sampler;
+
+fn iChannel0(uv: vec2f) -> vec4f {
+  return textureSample(channel0Tex, texSampler, uv);
+}
+fn iChannel1(uv: vec2f) -> vec4f {
+  return textureSample(channel1Tex, texSampler, uv);
+}
+fn iChannel2(uv: vec2f) -> vec4f {
+  return textureSample(channel2Tex, texSampler, uv);
+}
+fn iChannel3(uv: vec2f) -> vec4f {
+  return textureSample(channel3Tex, texSampler, uv);
+}
+
+struct VsOut {
+  @builtin(position) position: vec4f,
+  @location(0) uv: vec2f,
+}
+
+@vertex
+fn vs_main(@builtin(vertex_index) vi: u32) -> VsOut {
+  var pos = array<vec2f, 3>(
+    vec2f(-1.0, -1.0),
+    vec2f(3.0, -1.0),
+    vec2f(-1.0, 3.0),
+  );
+  var out: VsOut;
+  out.position = vec4f(pos[vi], 0.0, 1.0);
+  out.uv = pos[vi] * 0.5 + vec2f(0.5);
+  return out;
+}
+
+@fragment
+fn fs_main(in: VsOut) -> @location(0) vec4f {
+  let fragCoord = vec2f(in.uv.x * u.resolution.x, in.uv.y * u.resolution.y);
+  return mainImage(in.uv, fragCoord);
+}
+`.trim();
+
+/** Assemble prelude + corps utilisateur (ou défaut). */
+export function buildWgslSource(userBody: string): string {
+  const body = userBody.trim() || DEFAULT_MAIN_IMAGE;
+  if (!/\bfn\s+mainImage\s*\(/.test(body)) {
+    throw new Error(
+      "WGSL invalide : définir `fn mainImage(uv: vec2f, fragCoord: vec2f) -> vec4f`.",
+    );
+  }
+  return `${PRELUDE}\n\n${body}\n`;
+}

package/src/core/mixins/Fetcher.ts

@@ -160,7 +160,7 @@ const Fetcher = <
      * Elles sont ensuite injectées dans le publisher en accord avec la cible définie dans la propriété key
      * Un Toast est affiché si le chargement échoue
      */
-    async _fetchData() {
+    protected async _fetchData() {
       this.requestUpdate();
       if (!this.isFetchEnabled) return;
       this.api = new API(this.getApiConfiguration());

package/src/core/utils/HTML.ts

@@ -1,12 +1,29 @@
-// on désactive une regle eslint pour ce fichier
-/* eslint no-async-promise-executor: 0 */ // --> OFF
+/* eslint no-async-promise-executor: 0 */
 export type SearchableDomElement = HTMLElement | ShadowRoot;
 
 import { APIConfiguration } from "./api";
+
+/** Marqueur dataset : script déjà chargé avec succès via `loadJS`. */
+const SCRIPT_LOADED_FLAG = "1";
+
+/** http(s), relatif, blob — refuse javascript: / data: / etc. */
+function isAllowedScriptSrc(src: string): boolean {
+  const trimmed = src.trim();
+  if (!trimmed) return false;
+  try {
+    const url = new URL(trimmed, "https://example.invalid/");
+    return (
+      url.protocol === "http:" ||
+      url.protocol === "https:" ||
+      url.protocol === "blob:"
+    );
+  } catch {
+    return false;
+  }
+}
+
 class HTML {
-  /**
-   * retourne la langue de la page courante telle que défini via l'attribut lang de la balise html
-   */
+  /** Langue page : `SonicSelectedLanguage` localStorage, sinon `<html lang>`. */
   static getLanguage(): string {
     const documentLanguage = document.documentElement.lang;
     const selectedLanguage = localStorage.getItem("SonicSelectedLanguage");
@@ -40,13 +57,13 @@ class HTML {
 
   static everyAncestors(
     node: SearchableDomElement,
-    callback: (node: SearchableDomElement) => /*continue ?*/ boolean
+    callback: (node: SearchableDomElement) => boolean,
   ) {
-    while (node) {
-      const result = callback(node);
-      if (!result) return;
-      node = (node.parentNode ||
-        (node as ShadowRoot).host) as SearchableDomElement;
+    let current: SearchableDomElement | null = node;
+    while (current) {
+      if (!callback(current)) return;
+      current = (current.parentNode ||
+        (current as ShadowRoot).host) as SearchableDomElement;
     }
   }
 
@@ -115,22 +132,19 @@ class HTML {
   }
 
   /**
-   * Va de parent en parent en partant de node pour trouver un attribut.
-   * @param attributeName nom de l'attribut
-   * @returns valeur de l'attribut ou null si l'attribut n'est pas trouvé
+   * Première valeur d'attribut trouvée en remontant (parentNode / shadow host).
+   * Ne traverse pas les slots — volontairement distinct de `nextComposedAncestor`.
    */
   static getAncestorAttributeValue(
     node: SearchableDomElement | null,
-    attributeName: string
+    attributeName: string,
   ): string | null {
     if (!node) return null;
     let current: SearchableDomElement | null = node;
     while (current) {
       if (current instanceof HTMLElement) {
         const value = HTML.readScopeAttributeOnElement(current, attributeName);
-        if (value != null) {
-          return value;
-        }
+        if (value != null) return value;
       }
       const parent = current.parentNode || (current as ShadowRoot).host;
       if (!parent) break;
@@ -179,43 +193,34 @@ class HTML {
     };
   }
 
-  /**
-   * Va de parent en parent en partant de node pour trouver un attribut
-   * @param attributeName nom de l'attribut
-   * @returns valeur de l'attribut ou null si l'attribut n'est pas trouvé
-   */
+  /** Ancêtre dont le `nodeName` (minuscules) égale `selector` (ex. `"form"`). */
   static getClosestElement(node: SearchableDomElement, selector: string) {
-    while (!(node.nodeName && node.nodeName.toLowerCase() === selector)) {
-      const newNode = node.parentNode || (node as ShadowRoot).host;
-      if (!newNode) break;
-      node = (node.parentNode ||
-        (node as ShadowRoot).host) as SearchableDomElement;
-    }
-    if (!node.nodeName) {
-      return null;
+    let current: SearchableDomElement | null = node;
+    while (
+      current &&
+      !(current.nodeName && current.nodeName.toLowerCase() === selector)
+    ) {
+      const parent = current.parentNode || (current as ShadowRoot).host;
+      if (!parent) {
+        current = null;
+        break;
+      }
+      current = parent as SearchableDomElement;
     }
-    return node;
+    if (!current?.nodeName) return null;
+    return current;
   }
 
-  /**
-   * Va de parent en parent en partant de node pour trouver un attribut
-   * @param attributeName nom de l'attribut
-   * @returns valeur de l'attribut ou null si l'attribut n'est pas trouvé
-   */
   static getClosestForm(node: SearchableDomElement) {
     return HTML.getClosestElement(node, "form");
   }
 
   /**
-   * Parcourt les ancêtres (parentNode / shadow host) et collecte ceux dont le tagName
-   * correspond à l'un des noms fournis (comparaison insensible à la casse).
-   * @param node Élément de départ
-   * @param tagNames Noms de balises à rechercher (ex: ['sonic-subscriber', 'sonic-sdui'])
-   * @returns Tableau des ancêtres correspondants
+   * Ancêtres dont le tagName matche (insensible à la casse), via parentNode / shadow host.
    */
   static getAncestorsByTagNames(
     node: SearchableDomElement,
-    tagNames: string[]
+    tagNames: string[],
   ): Element[] {
     const normalized = new Set(tagNames.map((t) => t.toLowerCase()));
     const result: Element[] = [];
@@ -235,15 +240,11 @@ class HTML {
   }
 
   /**
-   * Parcourt les ancêtres (parentNode / shadow host) et collecte ceux qui matchent
-   * l'un des sélecteurs CSS fournis (element.matches(selector)).
-   * @param node Élément de départ
-   * @param selectors Sélecteurs CSS (ex: ['sonic-subscriber', 'sonic-sdui', 'div.container'])
-   * @returns Tableau des ancêtres correspondants
+   * Ancêtres qui matchent l'un des sélecteurs CSS (`element.matches`), via parentNode / shadow host.
    */
   static getAncestorsBySelectors(
     node: SearchableDomElement,
-    selectors: string[]
+    selectors: string[],
   ): Element[] {
     const result: Element[] = [];
     let current = (node.parentNode ||
@@ -257,7 +258,7 @@ class HTML {
               break;
             }
           } catch {
-            // Invalid selector, skip
+            /* sélecteur CSS invalide */
           }
         }
       }
@@ -268,24 +269,65 @@ class HTML {
   }
 
   /**
-   * Lance le chargement d'un js et retourne une promise qui resoud à true lorsque le chargement à réussi et à false, sinon.
-   * */
+   * Charge un JS ; true si succès, false sinon.
+   * `.es.js` / `?module` → `type="module"`. Déduplique sur `script.src` absolu.
+   * Refuse les schémas non scriptables (`javascript:`, `data:`, …).
+   */
   static async loadJS(src: string) {
-    const p = new Promise(async (resolve) => {
+    if (!isAllowedScriptSrc(src)) return false;
+    const absolute =
+      typeof document !== "undefined"
+        ? new URL(src, document.baseURI).href
+        : src;
+    const existing = Array.from(document.scripts).find(
+      (script) => script.src === absolute,
+    );
+    if (existing) {
+      if (existing.dataset.concordeLoaded === SCRIPT_LOADED_FLAG) return true;
+      return new Promise<boolean>((resolve) => {
+        let settled = false;
+        const finish = (ok: boolean) => {
+          if (settled) return;
+          settled = true;
+          if (ok) existing.dataset.concordeLoaded = SCRIPT_LOADED_FLAG;
+          resolve(ok);
+        };
+        existing.addEventListener("load", () => finish(true), { once: true });
+        existing.addEventListener("error", () => finish(false), {
+          once: true,
+        });
+        // Scripts déjà exécutés (injectés ailleurs) ne re-émettent pas `load`.
+        const rs = (existing as HTMLScriptElement & { readyState?: string })
+          .readyState;
+        if (rs === "complete" || rs === "loaded") {
+          finish(true);
+          return;
+        }
+        void Promise.resolve().then(() => {
+          void Promise.resolve().then(() => {
+            if (!settled) finish(true);
+          });
+        });
+      });
+    }
+    const asModule =
+      /\.es\.js(\?|#|$)/.test(src) || /[?&]module(?:&|=|$)/.test(src);
+    return new Promise((resolve) => {
       const script = document.createElement("script");
       script.src = src;
-      script.onload = () => resolve(true);
-      script.onerror = () => resolve(true);
+      if (asModule) script.type = "module";
+      script.onload = () => {
+        script.dataset.concordeLoaded = SCRIPT_LOADED_FLAG;
+        resolve(true);
+      };
+      script.onerror = () => resolve(false);
       document.head.appendChild(script);
     });
-    return p;
   }
 
-  /**
-   * Lance le chargement d'un css et retourne une promise qui resoud à true lorsque le chargement à réussi et à false, sinon.
-   * */
+  /** Charge un CSS ; résout toujours `true` (historique, y compris en erreur). */
   static async loadCSS(src: string) {
-    const p = new Promise(async (resolve) => {
+    return new Promise((resolve) => {
       const cssnode = document.createElement("link");
       cssnode.type = "text/css";
       cssnode.rel = "stylesheet";
@@ -294,29 +336,20 @@ class HTML {
       cssnode.onerror = () => resolve(true);
       document.head.appendChild(cssnode);
     });
-    return p;
   }
 }
 export default HTML;
 export const detecHTMLLanguageChange = (handler: () => void) => {
-  // Select the <html> element
   const htmlElement = document.documentElement;
-
-  // Create a new MutationObserver instance
   const observer = new MutationObserver((mutationsList) => {
-    for (let mutation of mutationsList) {
+    for (const mutation of mutationsList) {
       if (mutation.type === "attributes" && mutation.attributeName === "lang") {
         handler();
       }
     }
   });
-
-  // Observer configuration: watch for changes to attributes
-  const config = {
-    attributes: true, // Watch for attribute changes
-    attributeFilter: ["lang"], // Only watch for changes to the lang attribute
-  };
-
-  // Start observing the <html> element for changes
-  observer.observe(htmlElement, config);
+  observer.observe(htmlElement, {
+    attributes: true,
+    attributeFilter: ["lang"],
+  });
 };

package/src/core/utils/PublisherProxy.ts

@@ -786,10 +786,37 @@ export class PublisherManager {
     return new TextDecoder().decode(result);
   }
 }
+/**
+ * Partage le singleton entre le bundle core et les addons CDN (3d / shader / hf).
+ * Sans cela, chaque IIFE aurait sa propre classe `PublisherManager` et des
+ * dataProviders isolés.
+ */
 if (typeof window !== "undefined") {
   const win = window as any;
-  win[sonicClassPrefix + "PublisherManager"] =
-    win[sonicClassPrefix + "PublisherManager"] || PublisherManager;
+  const sharedKey = sonicClassPrefix + "PublisherManager";
+  const Shared = (win[sharedKey] || PublisherManager) as typeof PublisherManager;
+  if (!win[sharedKey]) win[sharedKey] = PublisherManager;
+  if (Shared !== PublisherManager) {
+    const syncKeys = [
+      "instance",
+      "instances",
+      "changed",
+      "saving",
+      "saveId",
+      "pageShowHandlerInitialized",
+    ] as const;
+    for (const key of syncKeys) {
+      Object.defineProperty(PublisherManager, key, {
+        configurable: true,
+        get() {
+          return (Shared as any)[key];
+        },
+        set(value) {
+          (Shared as any)[key] = value;
+        },
+      });
+    }
+  }
 }
 
 const internalProps: Set<string> = new Set([
@@ -1025,10 +1052,6 @@ export type Publisher<T = any> = DataProvider<T>;
 
 // if (typeof module != "undefined") module.exports = {DataProvider: DataProvider, PublisherManager: PublisherManager};
 
-// /**
-//  * A custom webcomponent wich will be linked to a publisher via its attribute "publisher"
-//  * the publisher will be found via PublisherManager.get(publisherId) and will be used to fill the component using the onAssign method
-//  */
 class PublisherWebComponent extends HTMLElement {
   publisherId = "";
   publisher: any;

package/src/core/utils/jsonataHelpers.ts

@@ -1,5 +1,7 @@
 import type { Expression } from "jsonata";
 import Format from "@supersoniks/concorde/core/utils/Format";
+import { toMediaUrl } from "@supersoniks/concorde/core/utils/mediaRef";
+import { cosine, rankBySimilarity } from "@supersoniks/concorde/core/utils/similarity";
 
 export type ChartDataset = {
   label?: string;
@@ -97,4 +99,38 @@ export function registerJsonataHelpers(expression: Expression): void {
       };
     },
   );
+
+  /** Similarité cosinus entre deux vecteurs (embeddings) : `$cosine(a, b)`. */
+  expression.registerFunction("cosine", (a: unknown, b: unknown) => cosine(a, b));
+
+  /**
+   * Classe des éléments par similarité : `$rankBySimilarity(items, vectors, query, topN?, minScore?)`.
+   * `vectors` est aligné sur `items` (sortie liste de `sonic-hugging-face-infer`).
+   * Chaque élément reçoit `_score`.
+   */
+  expression.registerFunction(
+    "rankBySimilarity",
+    (
+      items: unknown,
+      vectors: unknown,
+      query: unknown,
+      topN: unknown = 10,
+      minScore: unknown = -1,
+    ) =>
+      rankBySimilarity(
+        items as unknown[],
+        vectors as number[][],
+        query as number[],
+        Number(topN),
+        Number(minScore),
+      ),
+  );
+
+  /**
+   * URL média pour chaînage DP : `$mediaUrl(x)`.
+   * Accepte string | `{ url }` | `{ blobUrl }` — ne crée pas d’ObjectURL.
+   */
+  expression.registerFunction("mediaUrl", (value: unknown) =>
+    toMediaUrl(value),
+  );
 }

package/src/core/utils/mediaRef.spec.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import {
+  attachMediaUrls,
+  cloneMediaRef,
+  isMediaBlobObject,
+  revokeMediaUrls,
+  toMediaUrl,
+} from "./mediaRef";
+
+describe("toMediaUrl", () => {
+  it("accepte string / url / blobUrl", () => {
+    expect(toMediaUrl(" https://x/a.png ")).toBe("https://x/a.png");
+    expect(toMediaUrl({ url: "blob:abc" })).toBe("blob:abc");
+    expect(toMediaUrl({ blobUrl: "blob:xyz" })).toBe("blob:xyz");
+    expect(toMediaUrl(null)).toBeNull();
+    expect(toMediaUrl({ blob: new Blob() })).toBeNull();
+  });
+});
+
+describe("attachMediaUrls / revokeMediaUrls", () => {
+  const createSpy = vi.fn(() => "blob:mock-1");
+  const revokeSpy = vi.fn();
+
+  beforeEach(() => {
+    createSpy.mockClear();
+    revokeSpy.mockClear();
+    URL.createObjectURL = createSpy as typeof URL.createObjectURL;
+    URL.revokeObjectURL = revokeSpy as typeof URL.revokeObjectURL;
+  });
+
+  it("ajoute url sur les images Blob et collectes les ObjectURL", () => {
+    const blob = new Blob([new Uint8Array([1])], { type: "image/png" });
+    const depth: {
+      width: number;
+      height: number;
+      channels: number;
+      blob: Blob;
+      url?: string;
+    } = { width: 2, height: 2, channels: 1, blob };
+    const tree = { depth, other: 1 };
+    const created: string[] = [];
+    attachMediaUrls(tree, created);
+    expect(depth.url).toBe("blob:mock-1");
+    expect(created).toEqual(["blob:mock-1"]);
+    expect(isMediaBlobObject(depth)).toBe(true);
+    expect(createSpy).toHaveBeenCalledOnce();
+  });
+
+  it("conserve une url déjà présente (pas de nouvel ObjectURL)", () => {
+    const blob = new Blob([new Uint8Array([1])], { type: "image/png" });
+    const depth = {
+      width: 2,
+      height: 2,
+      blob,
+      url: "https://cdn.example/depth.png",
+    };
+    const created: string[] = [];
+    attachMediaUrls(depth, created);
+    expect(depth.url).toBe("https://cdn.example/depth.png");
+    expect(created).toEqual([]);
+    expect(createSpy).not.toHaveBeenCalled();
+  });
+
+  it("appelle revokeObjectURL", () => {
+    revokeMediaUrls(["blob:a", "blob:b"]);
+    expect(revokeSpy).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("cloneMediaRef", () => {
+  it("recrée un ObjectURL depuis un blob", async () => {
+    URL.createObjectURL = vi.fn(
+      () => "blob:cloned",
+    ) as typeof URL.createObjectURL;
+    const blob = new Blob([new Uint8Array([1, 2])], { type: "image/jpeg" });
+    const out = await cloneMediaRef({
+      url: "blob:old",
+      blob,
+      width: 2,
+      height: 2,
+    });
+    expect(out?.url).toBe("blob:cloned");
+    expect(out?.blob).toBe(blob);
+  });
+});

package/src/core/utils/mediaRef.ts

@@ -0,0 +1,130 @@
+/**
+ * Jeton média neutre pour chaîner HF → jsonata → shader / 3d via DataProvider.
+ *
+ * - `url` : http(s) | blob: | data: (préféré pour les canaux shader)
+ * - `blob` : binaire (HF, upload) — le producteur publie aussi `url` quand possible
+ * - `blobUrl` : alias historique (extract shader)
+ */
+
+export type SonicMediaRef = {
+  url?: string;
+  blobUrl?: string;
+  blob?: Blob;
+  width?: number;
+  height?: number;
+  mime?: string;
+};
+
+/** Objet image sérialisé (sortie HF / extract) : Blob + dimensions. */
+export function isMediaBlobObject(
+  value: unknown,
+): value is SonicMediaRef & { blob: Blob } {
+  if (!value || typeof value !== "object") return false;
+  const o = value as Record<string, unknown>;
+  return (
+    o.blob instanceof Blob &&
+    (typeof o.width === "number" ||
+      typeof o.height === "number" ||
+      typeof o.channels === "number" ||
+      typeof o.url === "string" ||
+      typeof o.blobUrl === "string")
+  );
+}
+
+/**
+ * Résout une URL affichable / chargeable sans créer d’ObjectURL.
+ * Accepte : string | objet avec `url` / `blobUrl` | null.
+ * Ne matérialise pas un `blob` seul — utiliser `attachMediaUrls` / `cloneMediaRef`.
+ */
+function nonEmptyTrimmed(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+
+export function toMediaUrl(value: unknown): string | null {
+  if (value == null || value === "") return null;
+  if (typeof value === "string") return nonEmptyTrimmed(value);
+  if (typeof value !== "object") return null;
+  const o = value as Record<string, unknown>;
+  return nonEmptyTrimmed(o.url) ?? nonEmptyTrimmed(o.blobUrl);
+}
+
+/**
+ * Attache un `url` (ObjectURL) à chaque nœud image `{ blob, width?, height? }`
+ * dans une arborescence. Mutates in place. Les URLs créées sont poussées dans
+ * `created` pour revoke ultérieur.
+ */
+export function attachMediaUrls(
+  value: unknown,
+  created: string[],
+): unknown {
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      value[i] = attachMediaUrls(value[i], created);
+    }
+    return value;
+  }
+  if (!value || typeof value !== "object") return value;
+  const o = value as Record<string, unknown>;
+  if (isMediaBlobObject(o)) {
+    // Ne pas écraser une url http(s)/blob déjà fournie par le producteur.
+    if (toMediaUrl(o)) return value;
+    const url = URL.createObjectURL(o.blob);
+    created.push(url);
+    o.url = url;
+    return value;
+  }
+  for (const key of Object.keys(o)) {
+    o[key] = attachMediaUrls(o[key], created);
+  }
+  return value;
+}
+
+/** Révoque une liste d’ObjectURL (ignore les erreurs). */
+export function revokeMediaUrls(urls: Iterable<string>): void {
+  for (const url of urls) {
+    try {
+      URL.revokeObjectURL(url);
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/**
+ * Copie durable d’un média : nouvel ObjectURL depuis `blob` (ou fetch de `url`).
+ * À utiliser quand on fige un `frameUrl` 3d — le producteur révoque sinon au frame suivant.
+ */
+export async function cloneMediaRef(
+  value: unknown,
+): Promise<SonicMediaRef | null> {
+  if (value == null) return null;
+  if (typeof value === "string") {
+    const url = value.trim();
+    if (!url) return null;
+    try {
+      const res = await fetch(url);
+      const blob = await res.blob();
+      const cloned = URL.createObjectURL(blob);
+      return { url: cloned, blob, mime: blob.type || undefined };
+    } catch {
+      return null;
+    }
+  }
+  if (typeof value !== "object") return null;
+  const o = value as SonicMediaRef;
+  if (o.blob instanceof Blob) {
+    const url = URL.createObjectURL(o.blob);
+    return {
+      url,
+      blob: o.blob,
+      width: o.width,
+      height: o.height,
+      mime: o.mime || o.blob.type || undefined,
+    };
+  }
+  const existing = toMediaUrl(o);
+  if (!existing) return null;
+  return cloneMediaRef(existing);
+}