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

package/src/core/components/functional/3d/runtime.ts

@@ -6,14 +6,22 @@ import { bootScene } from "./boot";
 import { ops, type OpsCtx } from "./ops";
 import type { SceneRuntimeOptions } from "./opts";
 import type { SceneHit } from "./pick";
+import {
+  PostFxCompileError,
+  PostFxPipeline,
+  type PostFxConfig,
+  type PostFxUniforms,
+} from "./post-fx";
 import { tune, type TuneCtx } from "./tune";
 import type { Sonic3dAsset, Sonic3dOutput } from "./types";
 import { view, type ViewCtx } from "./view";
 
 export type { SceneHit, SceneRuntimeOptions };
+export { PostFxCompileError };
+export type { PostFxConfig, PostFxUniforms };
 
 /**
- * Runtime Three.js encapsulé : renderer, scène, caméra, load, fit, pick.
+ * Runtime Three.js encapsulé : renderer, scène, caméra, load, fit, pick, post FX.
  * Le composant Lit gère RAF / viewport / DP.
  */
 export class SceneRuntime {
@@ -46,6 +54,19 @@ export class SceneRuntime {
   private highlighted: THREE.Mesh | null = null;
   private prevEmissive = new THREE.Color();
   private prevEmissiveIntensity = 0;
+  private postFx: PostFxPipeline;
+  private lastCssW = 1;
+  private lastCssH = 1;
+  private damping = 0.08;
+  private postFrame: PostFxUniforms = {
+    time: 0,
+    timeDelta: 1 / 60,
+    frame: 0,
+    mouse: [0, 0, 0, 0],
+    params: [0, 0, 0, 0],
+    near: 0.1,
+    far: 100,
+  };
 
   constructor(opts: SceneRuntimeOptions) {
     const b = bootScene(opts);
@@ -62,9 +83,32 @@ export class SceneRuntime {
     this.fov = b.fov;
     this.fitEnabled = b.fitEnabled;
     this.limits = b.limits;
+    this.postFx = new PostFxPipeline(this.renderer);
     this.applyCameraMode(this.mode);
     if (b.autoRotate) this.setAutoRotate(true);
-    void [this.canvas, this.perspCam, this.orthoCam, this.root, this.content, this.lights, this.loader, this.loadToken, this.blobUrl, this.dprMax, this.fov, this.fitEnabled, this.limits, this.bbox, this.target, this.raycaster, this.pointerNdc, this.highlighted, this.prevEmissive, this.prevEmissiveIntensity, this.unbindWheelRelay];
+    void [
+      this.canvas,
+      this.perspCam,
+      this.orthoCam,
+      this.root,
+      this.content,
+      this.lights,
+      this.loader,
+      this.loadToken,
+      this.blobUrl,
+      this.dprMax,
+      this.fov,
+      this.fitEnabled,
+      this.limits,
+      this.bbox,
+      this.target,
+      this.raycaster,
+      this.pointerNdc,
+      this.highlighted,
+      this.prevEmissive,
+      this.prevEmissiveIntensity,
+      this.unbindWheelRelay,
+    ];
   }
 
   get ready() {
@@ -79,6 +123,9 @@ export class SceneRuntime {
   get isLost() {
     return this.renderer.getContext()?.isContextLost?.() ?? false;
   }
+  get hasPostFx() {
+    return this.postFx.isEnabled;
+  }
 
   setDprMax(v: number) {
     tune.setDprMax(this.asTuneCtx(), v);
@@ -95,6 +142,15 @@ export class SceneRuntime {
   setAutoRotate(v: boolean) {
     tune.setAutoRotate(this.asTuneCtx(), v);
   }
+  setDamping(v: number) {
+    this.damping = Number.isFinite(v) ? Math.max(0, v) : 0.08;
+    tune.setDamping(this.asTuneCtx(), this.damping);
+  }
+  /** Coupe autoRotate + inertie OrbitControls. */
+  stopMotion() {
+    tune.setAutoRotate(this.asTuneCtx(), false);
+    tune.stopMotion(this.asTuneCtx());
+  }
   setOrbitLimits(opts: Parameters<typeof tune.setOrbitLimits>[1]) {
     tune.setOrbitLimits(this.asTuneCtx(), opts);
   }
@@ -104,9 +160,17 @@ export class SceneRuntime {
 
   applyCameraMode(mode: Sonic3dCameraMode) {
     view.applyCameraMode(this.asViewCtx(), mode);
+    tune.setDamping(this.asTuneCtx(), this.damping);
   }
   resize(cssW: number, cssH: number) {
+    this.lastCssW = cssW;
+    this.lastCssH = cssH;
     view.resize(this.asViewCtx(), cssW, cssH);
+    const dpr = Math.min(
+      typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1,
+      this.dprMax,
+    );
+    this.postFx.resize(cssW * dpr, cssH * dpr);
   }
   async load(asset: Sonic3dAsset | null) {
     return ops.runLoad(this.asOpsCtx(), asset);
@@ -114,9 +178,34 @@ export class SceneRuntime {
   fitToContent() {
     ops.fitToContent(this.asOpsCtx());
   }
+
+  setPostConfig(config: PostFxConfig | null) {
+    this.postFx.setConfig(config);
+    if (config && this.lastCssW > 0) {
+      this.resize(this.lastCssW, this.lastCssH);
+    }
+  }
+
+  setPostElementResolver(fn: ((key: string) => Element | null) | null) {
+    this.postFx.setElementResolver(fn);
+  }
+
+  setPostFrame(frame: Partial<PostFxUniforms>) {
+    Object.assign(this.postFrame, frame);
+    const cam = this.activeCam as THREE.PerspectiveCamera;
+    if ("near" in cam && "far" in cam) {
+      this.postFrame.near = cam.near;
+      this.postFrame.far = cam.far;
+    }
+  }
+
   render() {
     this.controls?.update();
-    this.renderer.render(this.scene, this.activeCam);
+    if (this.postFx.isEnabled) {
+      this.postFx.render(this.scene, this.activeCam, this.postFrame);
+    } else {
+      this.renderer.render(this.scene, this.activeCam);
+    }
   }
   pick(normX: number, normY: number): SceneHit | null {
     return ops.pick(this.asOpsCtx(), normX, normY);
@@ -138,6 +227,7 @@ export class SceneRuntime {
     return ops.buildSnapshot(this.asOpsCtx(), base);
   }
   dispose(loseContext = false) {
+    this.postFx.dispose();
     ops.dispose(this.asOpsCtx(), loseContext);
   }
 
@@ -145,4 +235,3 @@ export class SceneRuntime {
   private asViewCtx = () => this as unknown as ViewCtx;
   private asOpsCtx = () => this as unknown as OpsCtx;
 }
-

package/src/core/components/functional/3d/scene-runtime.ts

@@ -4,6 +4,9 @@
  */
 export {
   SceneRuntime,
+  PostFxCompileError,
   type SceneHit,
   type SceneRuntimeOptions,
+  type PostFxConfig,
+  type PostFxUniforms,
 } from "./runtime";

package/src/core/components/functional/3d/tune.ts

@@ -37,6 +37,25 @@ function setAutoRotate(ctx: TuneCtx, v: boolean) {
   if (ctx.controls) ctx.controls.autoRotate = v;
 }
 
+function setDamping(ctx: TuneCtx, v: number) {
+  if (!ctx.controls) return;
+  const d = Number.isFinite(v) ? Math.max(0, v) : 0.08;
+  ctx.controls.enableDamping = d > 0;
+  ctx.controls.dampingFactor = d > 0 ? d : 0.08;
+}
+
+/** Coupe autoRotate + vide l’inertie OrbitControls. */
+function stopMotion(ctx: TuneCtx) {
+  if (!ctx.controls) return;
+  ctx.controls.autoRotate = false;
+  const wasDamping = ctx.controls.enableDamping;
+  const factor = ctx.controls.dampingFactor;
+  ctx.controls.enableDamping = false;
+  ctx.controls.update();
+  ctx.controls.enableDamping = wasDamping;
+  ctx.controls.dampingFactor = factor;
+}
+
 function setOrbitLimits(ctx: TuneCtx, opts: Partial<OrbitLimits>) {
   ctx.limits = orbit.mergeLimits(ctx.limits, opts);
   orbit.applyLimitsToControls(ctx.controls, ctx.limits);
@@ -67,6 +86,8 @@ export const tune = {
   setFov,
   setFit,
   setAutoRotate,
+  setDamping,
+  stopMotion,
   setOrbitLimits,
   setOrbitSpherical,
 } as const;

package/src/core/components/functional/3d/types.ts

@@ -65,6 +65,13 @@ export type Sonic3dConfig = {
   playOnHover?: boolean;
   /** Libère le renderer hors viewport (défaut true). */
   releaseOffscreen?: boolean;
+  /**
+   * Garde RAF / runtime hors viewport (pont live).
+   * Aussi auto via `registerFrameConsumer`.
+   */
+  playOffscreen?: boolean;
+  /** Inertie OrbitControls (défaut 0.08, 0 = off). */
+  damping?: number;
   dprMax?: number;
   aspectRatio?: string;
 
@@ -124,6 +131,8 @@ export type Sonic3dOutput = {
   distance: number;
   yaw: number;
   pitch: number;
+  /** 1 si la caméra bouge (orbit / inertie / autoRotate), sinon 0. */
+  moving?: number;
   /** Présents après un pick réussi. */
   hitX?: number;
   hitY?: number;

package/src/core/components/functional/3d/updated.ts

@@ -3,6 +3,7 @@ import type { LifeHost } from "./life";
 import { life } from "./life";
 import { parse } from "./parse";
 import { playback } from "./playback";
+import { postBind } from "./post-bind";
 import { reload } from "./reload";
 
 function hasAny(
@@ -61,10 +62,25 @@ function updated(
   if (changed.has("autoRotate") || changed.has("play")) {
     playback.syncAutoRotate(host as never);
   }
-  if (changed.has("play") || changed.has("playOnHover")) {
+  if (
+    changed.has("play") ||
+    changed.has("playOnHover") ||
+    changed.has("playOffscreen")
+  ) {
     host.syncPlayback();
   }
+  if (changed.has("playOffscreen") || changed.has("releaseOffscreen")) {
+    ensure.syncVisibility(host as never);
+  }
+  if (changed.has("damping") && host.runtime) {
+    host.runtime.setDamping(
+      (host as unknown as { damping: number }).damping,
+    );
+  }
   if (changed.has("src") || changed.has("asset")) void reload.run(host as never);
+  if (postBind.propsChanged(changed)) {
+    postBind.applyConfig(host as never);
+  }
 }
 
 export const propUpdate = { updated } as const;

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

@@ -7,9 +7,11 @@ import {
   ChannelSource,
   PassChannels,
   ReadRectResult,
+  ShaderBufferFormat,
   ShaderCompileError,
   ShaderPassId,
   ShaderSources,
+  parseBufferFormat,
 } from "./types";
 
 const PASS_ORDER: ShaderPassId[] = [
@@ -235,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;
@@ -287,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]),
@@ -349,6 +435,7 @@ export class ShaderToyRuntime {
   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", {
@@ -364,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);
@@ -380,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();
@@ -416,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),
+        );
       }
     }
   }
@@ -458,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),
+        );
       }
     }
 
@@ -471,6 +601,18 @@ 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)));
@@ -846,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,
@@ -857,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,
+    );
   }
 
   /**
@@ -876,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;
@@ -895,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

@@ -44,8 +44,8 @@ Live 3D → shader (no JPEG): [Visual stack](#docs/_misc/visual-stack.md/visual-
 |--------|-----------|
 | Sortie d’un effet → entrée du suivant | `image-ch0="buffer-a"` (ou `buffer-b`… / `self`) — **même contexte GPU**, FBO ping-pong |
 | 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 |
+| 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 |
 
 Les passes intermédiaires sont **déjà offscreen** (FBO). Pas besoin d’un second `sonic-shader` invisible pour du multipass interne.
 
@@ -138,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 |
@@ -145,6 +161,7 @@ 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é |
+| `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`) |
@@ -170,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
 
@@ -184,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>