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

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

@@ -1,11 +1,17 @@
+import {
+  isFrameSource,
+  type SonicFrameSource,
+} from "@supersoniks/concorde/core/utils/mediaRef";
 import { buildFragmentSource, FULLSCREEN_VERTEX } from "./shadertoy-prelude";
 import {
   ChannelSource,
   PassChannels,
   ReadRectResult,
+  ShaderBufferFormat,
   ShaderCompileError,
   ShaderPassId,
   ShaderSources,
+  parseBufferFormat,
 } from "./types";
 
 const PASS_ORDER: ShaderPassId[] = [
@@ -55,6 +61,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 +75,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,
@@ -146,27 +237,110 @@ function getUniforms(
   };
 }
 
+type BufferGlFormat = {
+  requested: ShaderBufferFormat;
+  active: ShaderBufferFormat;
+  internal: number;
+  format: number;
+  type: number;
+  filter: number;
+  float: boolean;
+};
+
+let warnedFloatFallback = false;
+
+/**
+ * Résout le format GPU des buffers A–D.
+ * Exporté pour tests (mock `getExtension`).
+ */
+export function resolveBufferGlFormat(
+  gl: WebGL2RenderingContext,
+  requested: ShaderBufferFormat,
+): BufferGlFormat {
+  const want = parseBufferFormat(requested);
+  if (want === "rgba8") {
+    return {
+      requested: want,
+      active: "rgba8",
+      internal: gl.RGBA8,
+      format: gl.RGBA,
+      type: gl.UNSIGNED_BYTE,
+      filter: gl.LINEAR,
+      float: false,
+    };
+  }
+  const ext = gl.getExtension("EXT_color_buffer_float");
+  if (!ext) {
+    if (!warnedFloatFallback) {
+      warnedFloatFallback = true;
+      console.warn(
+        `[sonic-shader] buffer-format="${want}" indisponible (pas d'EXT_color_buffer_float) → rgba8`,
+      );
+    }
+    return resolveBufferGlFormat(gl, "rgba8");
+  }
+  if (want === "rgba16f") {
+    return {
+      requested: want,
+      active: "rgba16f",
+      internal: gl.RGBA16F,
+      format: gl.RGBA,
+      type: gl.HALF_FLOAT,
+      filter: gl.LINEAR,
+      float: true,
+    };
+  }
+  // rgba32f
+  const linearOk = !!gl.getExtension("OES_texture_float_linear");
+  return {
+    requested: want,
+    active: "rgba32f",
+    internal: gl.RGBA32F,
+    format: gl.RGBA,
+    type: gl.FLOAT,
+    filter: linearOk ? gl.LINEAR : gl.NEAREST,
+    float: true,
+  };
+}
+
+/** Reset du warn unique (tests). */
+export function resetBufferFormatWarnFlag() {
+  warnedFloatFallback = false;
+}
+
 function createEmptyTexture(
   gl: WebGL2RenderingContext,
   width: number,
   height: number,
+  fmt?: BufferGlFormat,
 ): WebGLTexture {
+  const f =
+    fmt ??
+    ({
+      requested: "rgba8",
+      active: "rgba8",
+      internal: gl.RGBA8,
+      format: gl.RGBA,
+      type: gl.UNSIGNED_BYTE,
+      filter: gl.LINEAR,
+      float: false,
+    } satisfies BufferGlFormat);
   const tex = gl.createTexture();
   if (!tex) throw new Error("Unable to create texture");
   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_MIN_FILTER, f.filter);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, f.filter);
   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,
+    f.internal,
     width,
     height,
     0,
-    gl.RGBA,
-    gl.UNSIGNED_BYTE,
+    f.format,
+    f.type,
     null,
   );
   return tex;
@@ -198,10 +372,11 @@ function createPingPong(
   gl: WebGL2RenderingContext,
   width: number,
   height: number,
+  fmt: BufferGlFormat,
 ): PingPong {
   const textures: [WebGLTexture, WebGLTexture] = [
-    createEmptyTexture(gl, width, height),
-    createEmptyTexture(gl, width, height),
+    createEmptyTexture(gl, width, height, fmt),
+    createEmptyTexture(gl, width, height, fmt),
   ];
   const framebuffers: [WebGLFramebuffer, WebGLFramebuffer] = [
     createFramebuffer(gl, textures[0]),
@@ -221,9 +396,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 +434,8 @@ 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;
+  private bufferFmt: BufferGlFormat;
 
   constructor(canvas: HTMLCanvasElement) {
     const gl = canvas.getContext("webgl2", {
@@ -271,6 +451,7 @@ export class ShaderToyRuntime {
     }
     this.canvas = canvas;
     this.gl = gl;
+    this.bufferFmt = resolveBufferGlFormat(gl, "rgba8");
     this.initGeometry();
     this.blackTexture = createEmptyTexture(gl, 1, 1);
     gl.bindTexture(gl.TEXTURE_2D, this.blackTexture);
@@ -287,6 +468,42 @@ export class ShaderToyRuntime {
     );
   }
 
+  /** Format réellement utilisé pour les buffers A–D (après repli éventuel). */
+  get activeBufferFormat(): ShaderBufferFormat {
+    return this.bufferFmt.active;
+  }
+
+  /**
+   * Change le format des buffers A–D. Recrée les FBO si la taille est déjà connue.
+   * Retourne le format actif (peut différer si extension manquante).
+   */
+  setBufferFormat(requested: ShaderBufferFormat): ShaderBufferFormat {
+    const next = resolveBufferGlFormat(this.gl, requested);
+    if (
+      next.active === this.bufferFmt.active &&
+      next.filter === this.bufferFmt.filter
+    ) {
+      this.bufferFmt = next;
+      return next.active;
+    }
+    this.bufferFmt = next;
+    if (this.width >= 1 && this.height >= 1) {
+      for (const id of BUFFER_PASSES) {
+        const existing = this.buffers.get(id);
+        if (existing) destroyPingPong(this.gl, existing);
+        if (this.programs.has(id)) {
+          this.buffers.set(
+            id,
+            createPingPong(this.gl, this.width, this.height, this.bufferFmt),
+          );
+        } else {
+          this.buffers.delete(id);
+        }
+      }
+    }
+    return next.active;
+  }
+
   /** True si le contexte a été perdu / déjà disposé. */
   get isLost(): boolean {
     return this.gl.isContextLost();
@@ -323,7 +540,10 @@ export class ShaderToyRuntime {
       const existing = this.buffers.get(id);
       if (existing) destroyPingPong(this.gl, existing);
       if (this.programs.has(id)) {
-        this.buffers.set(id, createPingPong(this.gl, w, h));
+        this.buffers.set(
+          id,
+          createPingPong(this.gl, w, h, this.bufferFmt),
+        );
       }
     }
   }
@@ -365,7 +585,10 @@ export class ShaderToyRuntime {
       if (pass !== "image" && this.width > 0) {
         const prev = this.buffers.get(pass);
         if (prev) destroyPingPong(this.gl, prev);
-        this.buffers.set(pass, createPingPong(this.gl, this.width, this.height));
+        this.buffers.set(
+          pass,
+          createPingPong(this.gl, this.width, this.height, this.bufferFmt),
+        );
       }
     }
 
@@ -378,40 +601,132 @@ export class ShaderToyRuntime {
     }
   }
 
+  /**
+   * Met à jour les bindings de canaux sans recompiler les programmes.
+   * Les URLs / clés `#élément` absentes des textures sont allouées à la demande
+   * (via `ensureTextures` / `ensureElementTexture` côté composant).
+   */
+  setPassChannels(channels: Map<ShaderPassId, PassChannels>) {
+    if (this.gl.isContextLost()) {
+      throw new Error("WebGL context lost");
+    }
+    this.passChannels = channels;
+  }
+
   async ensureTextures(urls: string[]) {
     const unique = [...new Set(urls.filter(Boolean))];
     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 +765,7 @@ export class ShaderToyRuntime {
           width: img.naturalWidth || img.width,
           height: img.naturalHeight || img.height,
           url,
+          lastSeq: 0,
         });
         resolve();
       };
@@ -503,6 +819,7 @@ export class ShaderToyRuntime {
           height: video.videoHeight,
           url,
           video,
+          lastSeq: 0,
         });
         void video.play().catch(() => {});
         resolve();
@@ -524,8 +841,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 +938,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);
@@ -665,6 +988,7 @@ export class ShaderToyRuntime {
 
   /**
    * Lit un rectangle d’un buffer ping-pong (dernier write) ou de l’Image (`pass === "image"`).
+   * Les buffers flottants renvoient un `Float32Array` ; Image / rgba8 → `Uint8Array`.
    */
   readBufferRect(
     pass: ShaderPassId,
@@ -676,7 +1000,14 @@ export class ShaderToyRuntime {
     if (pass === "image") return this.readRect(x, y, w, h);
     const pp = this.buffers.get(pass);
     if (!pp) return null;
-    return this.readFramebufferRect(pp.framebuffers[pp.index], x, y, w, h);
+    return this.readFramebufferRect(
+      pp.framebuffers[pp.index],
+      x,
+      y,
+      w,
+      h,
+      this.bufferFmt.float,
+    );
   }
 
   /**
@@ -695,6 +1026,7 @@ export class ShaderToyRuntime {
     y: number,
     w: number,
     h: number,
+    asFloat = false,
   ): ReadRectResult | null {
     const gl = this.gl;
     if (gl.isContextLost() || this.width < 1 || this.height < 1) return null;
@@ -714,9 +1046,15 @@ export class ShaderToyRuntime {
     if (px + pw > this.width) pw = this.width - px;
     if (py + ph > this.height) ph = this.height - py;
     if (pw < 1 || ph < 1) return null;
-    const data = new Uint8Array(pw * ph * 4);
     gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
-    gl.readPixels(px, py, pw, ph, gl.RGBA, gl.UNSIGNED_BYTE, data);
+    let data: Uint8Array | Float32Array;
+    if (asFloat) {
+      data = new Float32Array(pw * ph * 4);
+      gl.readPixels(px, py, pw, ph, gl.RGBA, gl.FLOAT, data);
+    } else {
+      data = new Uint8Array(pw * ph * 4);
+      gl.readPixels(px, py, pw, ph, gl.RGBA, gl.UNSIGNED_BYTE, data);
+    }
     gl.bindFramebuffer(gl.FRAMEBUFFER, null);
     return { x: px, y: py, width: pw, height: ph, data };
   }

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` |
-| 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.
+| 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`). Changer un canal ne recompile pas (rebind). |
+| Hors viewport | `release-offscreen` : `auto` (défaut) libère sauf si une passe lit `self` ; `true` / `false` forcent |
 
-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>
@@ -136,6 +138,22 @@ onExtract() {
 
 Live Harris → patches → WebGPU: [Visual stack](#docs/_misc/visual-stack.md/visual-stack).
 
+## Précision des buffers (`buffer-format`)
+
+Par défaut, les buffers A–D sont en **RGBA8** (unsigned). Un tenseur Harris naïf (`Ix*Ix`, `Iy*Iy`, `Ix*Iy`) **perd le signe** de `IxIy` et sature les carrés → bords au lieu de coins.
+
+| Valeur | Usage |
+|--------|--------|
+| `rgba8` (défaut) | Couleur / masques 0–1 |
+| `rgba16f` | Calculs signés (Harris, gradients) — recommandé |
+| `rgba32f` | Haute précision ; filtrage `NEAREST` si `OES_texture_float_linear` manque |
+
+Repli auto en `rgba8` si `EXT_color_buffer_float` est absent (`console.warn` une fois). L’attribut reflété `active-buffer-format` indique le format réellement utilisé. La passe Image reste le canvas RGBA8.
+
+```html
+<sonic-shader buffer-format="rgba16f" buffer-a="…" …></sonic-shader>
+```
+
 ## API typée (`SonicShaderConfig`)
 
 | Champ / attribut | Type | Rôle |
@@ -143,8 +161,9 @@ 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` |
+| `bufferFormat` / `buffer-format` | `rgba8` \| `rgba16f` \| `rgba32f` | Format buffers A–D (défaut `rgba8`) ; `active-buffer-format` reflète le format réellement utilisé |
+| `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`) |
@@ -168,7 +187,13 @@ Live Harris → patches → WebGPU: [Visual stack](#docs/_misc/visual-stack.md/v
 | `extractDataProvider` / `extract-data-provider` | `string` | Publisher extract (défaut = out) |
 | `aspectRatio` / `aspect-ratio` | `string` | Ratio CSS forcé |
 | `dprMax` / `dpr-max` | `number` | Plafond DPR (défaut `2`) |
-| `releaseOffscreen` / `release-offscreen` | `boolean` | Hors viewport : libère textures/FBO (garde le contexte). `dispose` + loseContext au disconnect (défaut `true`) |
+| `releaseOffscreen` / `release-offscreen` | `boolean` \| `"auto"` | Hors viewport : libère textures/FBO (garde le contexte). `auto` (défaut) : ne libère pas si une passe lit `self`. `dispose` + loseContext au disconnect |
+
+## État et visibilité
+
+Un shader qui garde un état via `self` (feedback frame précédente) n’est plus réinitialisé quand il sort de l’écran : avec `release-offscreen="auto"` (défaut), seuls le RAF et les vidéos sont mis en pause ; les FBO restent. Forcer `release-offscreen` (attribut booléen / `true`) restaure l’ancien comportement (libération hors viewport même avec `self`).
+
+Changer `channel0…3` / `*-ch*` re-lie les textures **sans** recompiler ni vider les buffers.
 
 ## Markup
 
@@ -182,7 +207,7 @@ Live Harris → patches → WebGPU: [Visual stack](#docs/_misc/visual-stack.md/v
   hover-speed="12"
   play
   play-on-hover
-  release-offscreen
+  release-offscreen="auto"
   channel0="/docs/shader-samples/color.jpg"
 &gt;&lt;/sonic-shader&gt;
   </template>