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

package/src/core/components/functional/shader/gl-runtime.ts

@@ -1,3 +1,7 @@
+import {
+  isFrameSource,
+  type SonicFrameSource,
+} from "@supersoniks/concorde/core/utils/mediaRef";
 import { buildFragmentSource, FULLSCREEN_VERTEX } from "./shadertoy-prelude";
 import {
   ChannelSource,
@@ -55,6 +59,10 @@ type ExternalTexture = {
   height: number;
   url: string;
   video?: HTMLVideoElement;
+  /** Source live (`#élément`) — image / vidéo / canvas / SonicFrameSource. */
+  source?: TexImageSource | SonicFrameSource | null;
+  lastSeq: number;
+  lastSrc?: string;
 };
 
 export type FrameUniforms = {
@@ -65,10 +73,91 @@ export type FrameUniforms = {
   params: [number, number, number, number];
 };
 
+/**
+ * Décide si un slot élément doit être re-uploadé cette frame.
+ * Exporté pour les tests unitaires (stratégie par type).
+ */
+export function shouldUploadElementFrame(
+  source: unknown,
+  lastSeq: number,
+  lastSrc?: string,
+): { upload: boolean; texSource: TexImageSource | null; nextSrc?: string } {
+  if (!source) return { upload: false, texSource: null };
+  if (
+    typeof HTMLImageElement !== "undefined" &&
+    source instanceof HTMLImageElement
+  ) {
+    const src = source.currentSrc || source.src || "";
+    if (!src || !source.complete || source.naturalWidth < 1) {
+      return { upload: false, texSource: null };
+    }
+    if (lastSrc === src && lastSeq > 0) {
+      return { upload: false, texSource: null, nextSrc: src };
+    }
+    return { upload: true, texSource: source, nextSrc: src };
+  }
+  if (
+    typeof HTMLVideoElement !== "undefined" &&
+    source instanceof HTMLVideoElement
+  ) {
+    if (source.readyState < 2 || source.videoWidth < 1) {
+      return { upload: false, texSource: null };
+    }
+    return { upload: true, texSource: source };
+  }
+  if (
+    typeof HTMLCanvasElement !== "undefined" &&
+    source instanceof HTMLCanvasElement
+  ) {
+    if (source.width < 1 || source.height < 1) {
+      return { upload: false, texSource: null };
+    }
+    return { upload: true, texSource: source };
+  }
+  if (isFrameSource(source)) {
+    if (source.frameSeq === lastSeq) {
+      return { upload: false, texSource: null };
+    }
+    const canvas = source.getFrameCanvas();
+    if (!canvas || canvas.width < 1 || canvas.height < 1) {
+      return { upload: false, texSource: null };
+    }
+    return { upload: true, texSource: canvas };
+  }
+  return { upload: false, texSource: null };
+}
+
 function isVideoUrl(url: string): boolean {
   return /\.(webm|mp4|ogg|mov)(\?|#|$)/i.test(url);
 }
 
+function texImageSourceSize(
+  src: TexImageSource,
+): { width: number; height: number } {
+  if (
+    typeof HTMLVideoElement !== "undefined" &&
+    src instanceof HTMLVideoElement
+  ) {
+    return { width: src.videoWidth || 1, height: src.videoHeight || 1 };
+  }
+  if (
+    typeof HTMLImageElement !== "undefined" &&
+    src instanceof HTMLImageElement
+  ) {
+    return {
+      width: src.naturalWidth || src.width || 1,
+      height: src.naturalHeight || src.height || 1,
+    };
+  }
+  if ("width" in src && "height" in src) {
+    return {
+      width: Math.max(1, Number(src.width) || 1),
+      height: Math.max(1, Number(src.height) || 1),
+    };
+  }
+  return { width: 1, height: 1 };
+}
+
 function compileShader(
   gl: WebGL2RenderingContext,
   type: number,
@@ -221,9 +310,12 @@ export function parseChannelSource(
 ): ChannelSource {
   const v = (value ?? "").trim();
   if (!v) {
-    return fallbackUrl
-      ? { kind: "url", url: fallbackUrl }
-      : { kind: "none" };
+    const fb = (fallbackUrl ?? "").trim();
+    if (fb.startsWith("#")) return { kind: "element", key: fb };
+    return fb ? { kind: "url", url: fb } : { kind: "none" };
+  }
+  if (v.startsWith("#")) {
+    return { kind: "element", key: v };
   }
   const lower = v.toLowerCase();
   if (lower === "self") return { kind: "self" };
@@ -256,6 +348,7 @@ export class ShaderToyRuntime {
   private passChannels = new Map<ShaderPassId, PassChannels>();
   private activePasses: ShaderPassId[] = [];
   private blackTexture: WebGLTexture | null = null;
+  private elementResolver: ((key: string) => Element | null) | null = null;
 
   constructor(canvas: HTMLCanvasElement) {
     const gl = canvas.getContext("webgl2", {
@@ -383,35 +476,115 @@ export class ShaderToyRuntime {
     await Promise.all(unique.map((url) => this.loadTexture(url)));
   }
 
-  /** Upload the current video frame for any channel backed by a video element. */
-  updateVideoTextures() {
+  /** Alloue un slot texture vide pour un canal `#élément` (upload live ensuite). */
+  ensureElementTexture(key: string) {
+    if (this.external.has(key)) return;
     const gl = this.gl;
-    for (const ext of this.external.values()) {
-      const video = ext.video;
-      if (!video || video.readyState < 2) continue;
+    const tex = gl.createTexture();
+    if (!tex) return;
+    gl.bindTexture(gl.TEXTURE_2D, tex);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.texImage2D(
+      gl.TEXTURE_2D,
+      0,
+      gl.RGBA8,
+      1,
+      1,
+      0,
+      gl.RGBA,
+      gl.UNSIGNED_BYTE,
+      new Uint8Array([0, 0, 0, 255]),
+    );
+    this.external.set(key, {
+      texture: tex,
+      width: 1,
+      height: 1,
+      url: key,
+      lastSeq: 0,
+    });
+  }
+
+  /**
+   * Upload live des canaux élément / vidéo.
+   * `resolveEl(key)` fournit l’Element (résolution `#id` côté host).
+   */
+  updateElementTextures(resolveEl?: (key: string) => Element | null) {
+    const gl = this.gl;
+    for (const [key, ext] of this.external) {
+      let source: unknown = ext.video ?? ext.source ?? null;
+      // Canaux #id : re-résoudre chaque frame (élément peut apparaître / partir).
+      if (key.startsWith("#") && resolveEl) {
+        source = resolveEl(key);
+        ext.source = source as TexImageSource | SonicFrameSource | null;
+      }
+      if (
+        typeof HTMLVideoElement !== "undefined" &&
+        source instanceof HTMLVideoElement
+      ) {
+        ext.video = source;
+      }
+      const decision = shouldUploadElementFrame(
+        source,
+        ext.lastSeq,
+        ext.lastSrc,
+      );
+      if (!decision.upload || !decision.texSource) continue;
+      const size = texImageSourceSize(decision.texSource);
       gl.bindTexture(gl.TEXTURE_2D, ext.texture);
       gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 1);
-      gl.texImage2D(
-        gl.TEXTURE_2D,
-        0,
-        gl.RGBA8,
-        gl.RGBA,
-        gl.UNSIGNED_BYTE,
-        video,
-      );
+      if (ext.width === size.width && ext.height === size.height && ext.lastSeq > 0) {
+        gl.texSubImage2D(
+          gl.TEXTURE_2D,
+          0,
+          0,
+          0,
+          gl.RGBA,
+          gl.UNSIGNED_BYTE,
+          decision.texSource,
+        );
+      } else {
+        gl.texImage2D(
+          gl.TEXTURE_2D,
+          0,
+          gl.RGBA8,
+          gl.RGBA,
+          gl.UNSIGNED_BYTE,
+          decision.texSource,
+        );
+        ext.width = size.width;
+        ext.height = size.height;
+      }
       gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 0);
-      ext.width = video.videoWidth || ext.width;
-      ext.height = video.videoHeight || ext.height;
+      if (isFrameSource(source)) {
+        ext.lastSeq = source.frameSeq;
+      } else {
+        ext.lastSeq = (ext.lastSeq || 0) + 1;
+      }
+      if (decision.nextSrc !== undefined) ext.lastSrc = decision.nextSrc;
     }
   }
 
+  /** @deprecated alias — préférer `updateElementTextures`. */
+  updateVideoTextures() {
+    this.updateElementTextures();
+  }
+
   setVideosPlaying(playing: boolean) {
     for (const ext of this.external.values()) {
-      if (!ext.video) continue;
+      const video =
+        ext.video ||
+        (typeof HTMLVideoElement !== "undefined" &&
+        ext.source instanceof HTMLVideoElement
+          ? ext.source
+          : null);
+      if (!video) continue;
       if (playing) {
-        void ext.video.play().catch(() => {});
+        void video.play().catch(() => {});
       } else {
-        ext.video.pause();
+        video.pause();
       }
     }
   }
@@ -450,6 +623,7 @@ export class ShaderToyRuntime {
           width: img.naturalWidth || img.width,
           height: img.naturalHeight || img.height,
           url,
+          lastSeq: 0,
         });
         resolve();
       };
@@ -503,6 +677,7 @@ export class ShaderToyRuntime {
           height: video.videoHeight,
           url,
           video,
+          lastSeq: 0,
         });
         void video.play().catch(() => {});
         resolve();
@@ -524,8 +699,9 @@ export class ShaderToyRuntime {
       height: 1,
     };
     if (source.kind === "none") return black;
-    if (source.kind === "url") {
-      const ext = this.external.get(source.url);
+    if (source.kind === "url" || source.kind === "element") {
+      const key = source.kind === "url" ? source.url : source.key;
+      const ext = this.external.get(key);
       return ext
         ? { texture: ext.texture, width: ext.width, height: ext.height }
         : black;
@@ -620,10 +796,15 @@ export class ShaderToyRuntime {
     }
   }
 
+  /** Host fournit la résolution `#id` / live Element. */
+  setElementResolver(fn: ((key: string) => Element | null) | null) {
+    this.elementResolver = fn;
+  }
+
   render(frame: FrameUniforms) {
     const gl = this.gl;
     if (!this.vao || this.width < 1 || this.height < 1) return;
-    this.updateVideoTextures();
+    this.updateElementTextures(this.elementResolver ?? undefined);
     gl.bindVertexArray(this.vao);
     gl.viewport(0, 0, this.width, this.height);
     gl.disable(gl.DEPTH_TEST);

package/src/core/components/functional/shader/shader.md

@@ -24,7 +24,7 @@ CDN (after the core): `concorde-shader.bundle.js` — see [CDN addons](#docs/_ge
 
 Uniforms supportés : `iResolution`, `iTime`, `iTimeDelta`, `iFrame`, `iFrameRate`, `iMouse`, `iDate`, `iChannel0–3`, `iChannelResolution`, `iChannelTime`, `iSampleRate`, `uParam0–3`.
 
-Textures `channel0–3` : images **ou** vidéos (`.webm` / `.mp4` / …).
+Textures `channel0–3` : images, vidéos (`.webm` / `.mp4` / …), **ou** éléments page via `#id` (`<img>`, `<video>`, `<canvas>`, `sonic-3d` / `sonic-webgpu` / `sonic-shader`).
 
 ## Multipass sur une photo
 
@@ -34,20 +34,22 @@ Buffer A simule une height-map d’ondes (ripple) ; Image réfracte la photo via
 
 Photo + depth parallax (HF): [Visual stack](#docs/_misc/visual-stack.md/visual-stack).
 
+Live 3D → shader (no JPEG): [Visual stack](#docs/_misc/visual-stack.md/visual-stack).
+
 ## Chaînage d’effets (officiel)
 
-**Règle :** brancher des passes dans **un** `sonic-shader` (buffers `A–D` → `Image`), pas deux composants via dataProvider.
+**Règle :** brancher des passes dans **un** `sonic-shader` (buffers `A–D` → `Image`), pas deux composants via dataProvider — **sauf** pont live `#élément` (copie canvas chaque frame).
 
 | Besoin | Mécanisme |
 |--------|-----------|
 | Sortie d’un effet → entrée du suivant | `image-ch0="buffer-a"` (ou `buffer-b`… / `self`) — **même contexte GPU**, FBO ping-pong |
-| Params / sync UI | `dataProvider` → `uParam0…3` **et** canaux (`channel0`, `bufferACh0`…) — string URL ou `SonicMediaRef` |
+| Scene 3D / autre canvas → post | `channel0="#plateau"` — copie `texImage2D` chaque `frameSeq` |
+| Params / sync UI | `dataProvider` → `uParam0…3` **et** canaux (`channel0`, `bufferACh0`…) — string URL, `#id`, ou `SonicMediaRef` (`url` / `element`) |
 | Hors viewport | `release-offscreen` (défaut) : libère textures/FBO, garde le contexte |
 
-Les passes intermédiaires sont **déjà offscreen** (FBO). Pas besoin d’un second `sonic-shader` invisible.
-
-Deux instances séparées ne partagent pas leurs textures WebGL (contextes distincts). Un bus texture via DP n’existe pas (et un `toBlob`/`dataURL` ne serait pas temps réel).
+Les passes intermédiaires sont **déjà offscreen** (FBO). Pas besoin d’un second `sonic-shader` invisible pour du multipass interne.
 
+Deux instances séparées ne partagent pas leurs textures WebGL (contextes distincts). Le pont live `#id` **copie** le canvas source ; `frame-out` JPEG reste pour export / freeze.
 Démo pédagogique : Buffer&nbsp;A = Sobel → Image = overlay + `param0`.
 
 <docs-lit-demo for="docs-shader-chain-demo"></docs-lit-demo>
@@ -143,8 +145,8 @@ Live Harris → patches → WebGPU: [Visual stack](#docs/_misc/visual-stack.md/v
 | `image` | `string` | GLSL pass Image (**requis**, propriété JS) |
 | `bufferA`…`bufferD` / `buffer-a`… | `string` | Passes multipass |
 | `common` | `string` | GLSL partagé |
-| `channel0`…`channel3` | `string` | URLs textures (toutes passes) |
-| `imageCh0`… / `image-ch0`… | `string` | Override canal : URL, `self`, `buffer-a`…, `none` |
+| `channel0`…`channel3` | `string` | URLs, `#id` élément, ou refs buffers (toutes passes) |
+| `imageCh0`… / `image-ch0`… | `string` | Override canal : URL, `#id`, `self`, `buffer-a`…, `none` |
 | `play` | `boolean` | Boucle RAF (défaut `true`) |
 | `playOnHover` / `play-on-hover` | `boolean` | Anime seulement au hover / transition |
 | `mouse` | `boolean` | Pointeur → `iMouse` (défaut `true`) |

package/src/core/components/functional/shader/shader.spec.ts

@@ -1,9 +1,12 @@
 import { expect, describe, it, vi, afterEach, beforeAll } from "vitest";
 import TestUtils from "@supersoniks/concorde/test-utils/TestUtils";
-import { parseChannelSource } from "./gl-runtime";
+import {
+  parseChannelSource,
+  shouldUploadElementFrame,
+} from "./gl-runtime";
 import { buildFragmentSource } from "./shadertoy-prelude";
 import "./shader";
-import { SonicShader } from "./shader";
+import { SonicShader, channelFormValue } from "./shader";
 
 describe("parseChannelSource", () => {
   it("résout self / buffers / url / fallback", () => {
@@ -26,6 +29,81 @@ describe("parseChannelSource", () => {
     });
     expect(parseChannelSource("none", "")).toEqual({ kind: "none" });
   });
+
+  it("résout #id comme élément (pas URL)", () => {
+    expect(parseChannelSource("#plateau", "")).toEqual({
+      kind: "element",
+      key: "#plateau",
+    });
+    expect(parseChannelSource("", "#scene")).toEqual({
+      kind: "element",
+      key: "#scene",
+    });
+  });
+});
+
+describe("channelFormValue", () => {
+  it("passe { element } → #id", () => {
+    expect(channelFormValue({ element: "#plateau" })).toBe("#plateau");
+    expect(channelFormValue({ element: "plateau" })).toBe("#plateau");
+    expect(channelFormValue({ url: "https://x/a.png" })).toBe(
+      "https://x/a.png",
+    );
+    expect(channelFormValue({ blob: new Blob() })).toBeUndefined();
+  });
+});
+
+describe("shouldUploadElementFrame", () => {
+  it("canvas : upload chaque frame si taille ok", () => {
+    const canvas = document.createElement("canvas");
+    canvas.width = 4;
+    canvas.height = 4;
+    expect(shouldUploadElementFrame(canvas, 0).upload).toBe(true);
+    expect(shouldUploadElementFrame(canvas, 3).upload).toBe(true);
+  });
+
+  it("FrameSource : skip si frameSeq inchangé, upload sinon", () => {
+    const canvas = document.createElement("canvas");
+    canvas.width = 2;
+    canvas.height = 2;
+    const src = {
+      frameSeq: 5,
+      getFrameCanvas: () => canvas,
+    };
+    expect(shouldUploadElementFrame(src, 5).upload).toBe(false);
+    const up = shouldUploadElementFrame(src, 4);
+    expect(up.upload).toBe(true);
+    expect(up.texSource).toBe(canvas);
+  });
+
+  it("source absente → pas d’upload (texture noire côté runtime)", () => {
+    expect(shouldUploadElementFrame(null, 0).upload).toBe(false);
+    expect(
+      shouldUploadElementFrame(
+        { frameSeq: 1, getFrameCanvas: () => null },
+        0,
+      ).upload,
+    ).toBe(false);
+  });
+
+  it("image : upload au changement de src seulement", () => {
+    const img = document.createElement("img");
+    Object.defineProperty(img, "complete", { value: true });
+    Object.defineProperty(img, "naturalWidth", { value: 8 });
+    Object.defineProperty(img, "naturalHeight", { value: 8 });
+    Object.defineProperty(img, "currentSrc", {
+      value: "https://example.test/a.png",
+    });
+    const first = shouldUploadElementFrame(img, 0);
+    expect(first.upload).toBe(true);
+    expect(first.nextSrc).toBe("https://example.test/a.png");
+    const again = shouldUploadElementFrame(
+      img,
+      1,
+      "https://example.test/a.png",
+    );
+    expect(again.upload).toBe(false);
+  });
 });
 
 describe("buildFragmentSource", () => {
@@ -207,7 +285,7 @@ describe("SonicShader", () => {
     expect(el.param0).toBe(0.99);
   });
 
-  it("applique les canaux depuis dataProvider (url | MediaRef)", async () => {
+  it("applique les canaux depuis dataProvider (url | MediaRef | element)", async () => {
     const { PublisherManager } = await import(
       "@supersoniks/concorde/utils"
     );
@@ -217,6 +295,7 @@ describe("SonicShader", () => {
       bufferACh0: { url: "https://example.test/depth.png" },
       imageCh0: "buffer-a",
       imageCh1: "https://example.test/color.jpg",
+      channel0: { element: "#plateau" },
       param0: 0.5,
     });
     const el = TestUtils.bootstrap(
@@ -228,6 +307,7 @@ describe("SonicShader", () => {
     expect(el.bufferACh0).toBe("https://example.test/depth.png");
     expect(el.imageCh0).toBe("buffer-a");
     expect(el.imageCh1).toBe("https://example.test/color.jpg");
+    expect(el.channel0).toBe("#plateau");
     expect(el.param0).toBe(0.5);
   });
 

package/src/core/components/functional/shader/shader.ts

@@ -1,7 +1,7 @@
 import { css, html, LitElement } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
 import HTML from "@supersoniks/concorde/core/utils/HTML";
-import { revokeMediaUrls, toMediaUrl } from "@supersoniks/concorde/core/utils/mediaRef";
+import { revokeMediaUrls, toMediaUrl, mediaElementKey, lookupLiveElement } from "@supersoniks/concorde/core/utils/mediaRef";
 import { PublisherManager } from "@supersoniks/concorde/utils";
 import {
   parseChannelSource,
@@ -104,16 +104,24 @@ function toNum(v: unknown, fallback: number): number {
   return fallback;
 }
 
-/** Valeur canal depuis DP : string (url ou buffer-a) | MediaRef → url. */
+/** Valeur canal depuis DP : string (url, buffer-a, #id) | MediaRef → url | { element }. */
 function channelFormValue(value: unknown): string | undefined {
   if (value === null || value === "") return "";
   if (typeof value === "string") return value.trim();
   const url = toMediaUrl(value);
   if (url) return url;
-  if (value && typeof value === "object") return undefined;
+  if (value && typeof value === "object") {
+    const el = (value as { element?: unknown }).element;
+    const key = mediaElementKey(el);
+    if (key) return key;
+    return undefined;
+  }
   return "";
 }
 
+/** Exposé pour tests. */
+export { channelFormValue };
+
 function parseRois(value: unknown): ShaderRoi[] {
   if (!Array.isArray(value)) return [];
   const out: ShaderRoi[] = [];
@@ -364,6 +372,8 @@ export class SonicShader extends LitElement {
   private startTime = 0;
   private lastTime = 0;
   private frame = 0;
+  /** Incrémenté après chaque render (contrat SonicFrameSource). */
+  frameSeq = 0;
   private mouseVec: [number, number, number, number] = [0, 0, 0, 0];
   /** Cible pointeur (px drawing buffer, origine bas-gauche). */
   private mouseTarget: [number, number] = [0, 0];
@@ -702,6 +712,27 @@ export class SonicShader extends LitElement {
     );
   }
 
+  /** Contrat SonicFrameSource — canvas lisible pour un autre sonic-shader. */
+  getFrameCanvas(): HTMLCanvasElement | null {
+    if (!this.ready || !this.runtime || this.runtime.isLost) return null;
+    return this.getCanvas();
+  }
+
+  /** Résout `#id` dans getRootNode() puis document ; clés live `__sonic_frame_`. */
+  private lookupElement(key: string): Element | null {
+    if (!key.startsWith("#")) return null;
+    const live = lookupLiveElement(key);
+    if (live) return live;
+    const id = key.slice(1);
+    if (!id || id.startsWith("__sonic_frame_")) return null;
+    const root = this.getRootNode();
+    if (root instanceof Document || root instanceof ShadowRoot) {
+      const el = root.getElementById(id);
+      if (el) return el;
+    }
+    return typeof document !== "undefined" ? document.getElementById(id) : null;
+  }
+
   private bindContextEvents() {
     const canvas = this.getCanvas();
     canvas?.addEventListener("webglcontextlost", this.onContextLost);
@@ -743,6 +774,7 @@ export class SonicShader extends LitElement {
     try {
       this.errorMessage = "";
       this.runtime = new ShaderToyRuntime(canvas);
+      this.runtime.setElementResolver((key) => this.lookupElement(key));
       this.bindContextEvents();
       this.syncSize();
       await this.rebuild();
@@ -827,6 +859,18 @@ export class SonicShader extends LitElement {
     return urls;
   }
 
+  private collectElementKeys(
+    channels: Map<ShaderPassId, PassChannels>,
+  ): string[] {
+    const keys: string[] = [];
+    for (const chs of channels.values()) {
+      for (const c of chs) {
+        if (c.kind === "element") keys.push(c.key);
+      }
+    }
+    return [...new Set(keys)];
+  }
+
   private async rebuild() {
     if (!this.runtime || this.runtime.isLost || !this.image.trim()) return;
     const token = ++this.rebuildToken;
@@ -853,10 +897,15 @@ export class SonicShader extends LitElement {
       this.syncSize();
       const urls = this.collectUrls(channels);
       await this.runtime.ensureTextures(urls);
+      for (const key of this.collectElementKeys(channels)) {
+        this.runtime.ensureElementTexture(key);
+      }
       if (token !== this.rebuildToken || !this.runtime || this.runtime.isLost) {
         return;
       }
-      this.applyAspectRatio(this.channel0 || urls[0]);
+      const aspectHint =
+        this.channel0.startsWith("#") ? "" : this.channel0 || urls[0];
+      this.applyAspectRatio(aspectHint);
       this.syncSize();
       this.runtime.setSources(sources, channels);
       if (token !== this.rebuildToken || !this.runtime || this.runtime.isLost) {
@@ -964,6 +1013,7 @@ export class SonicShader extends LitElement {
       mouse: this.mouseVec,
       params,
     });
+    this.frameSeq++;
     this.maybePublishOut(now, time, params);
     void this.maybeExtract(now, time);
   }
@@ -1531,7 +1581,7 @@ export class SonicShader extends LitElement {
   }
 }
 
-export { parseChannelSource, ShaderToyRuntime } from "./gl-runtime";
+export { parseChannelSource, ShaderToyRuntime, shouldUploadElementFrame } from "./gl-runtime";
 export { buildFragmentSource } from "./shadertoy-prelude";
 export type {
   ChannelSource,
@@ -1548,10 +1598,15 @@ export type {
   SonicShaderConfig,
   SonicShaderOutput,
 } from "./types";
-export type { SonicMediaRef } from "@supersoniks/concorde/core/utils/mediaRef";
+export type {
+  SonicMediaRef,
+  SonicFrameSource,
+} from "@supersoniks/concorde/core/utils/mediaRef";
 export {
   toMediaUrl,
   cloneMediaRef,
+  isFrameSource,
+  mediaElementKey,
 } from "@supersoniks/concorde/core/utils/mediaRef";
 export {
   findPeaks,

package/src/core/components/functional/shader/types.ts

@@ -9,7 +9,9 @@ export type ChannelSource =
   | { kind: "url"; url: string }
   | { kind: "buffer"; buffer: Exclude<ShaderPassId, "image"> }
   | { kind: "self" }
-  | { kind: "none" };
+  | { kind: "none" }
+  /** Élément page (`#id`) — upload live via `updateElementTextures`. */
+  | { kind: "element"; key: string; el?: Element | null };
 
 export type PassChannels = [
   ChannelSource,

package/src/core/components/functional/webgpu/webgpu.ts

@@ -138,6 +138,8 @@ export class SonicWebGpu extends LitElement {
   raf = 0;
   startTime = 0;
   frame = 0;
+  /** Contrat SonicFrameSource — incrémenté après chaque draw. */
+  frameSeq = 0;
   mouseVec: [number, number, number, number] = [0, 0, 0, 0];
   /** Cible normalisée (0–1, origine haut-gauche) depuis dataProvider — tracking / DP. */
   remoteTarget: { x: number; y: number } | null = null;
@@ -596,6 +598,7 @@ export class SonicWebGpu extends LitElement {
               params: [this.param0, this.param1, this.param2, this.param3],
             });
             this.frame++;
+            this.frameSeq++;
             this.maybePublishOut(now, time);
           } catch (e) {
             console.warn(`${LOG_PREFIX} frame skip:`, e);
@@ -620,6 +623,12 @@ export class SonicWebGpu extends LitElement {
     outFrame.maybePublishOut(this as never, now, time);
   }
 
+  /** Contrat SonicFrameSource — canvas WebGPU / fallback. */
+  getFrameCanvas(): HTMLCanvasElement | null {
+    if (!this.ready || this.errorMessage) return null;
+    return this.canvasEl;
+  }
+
   private revokeFrameUrl() {
     outFrame.revokeFrameUrl(this as never);
   }