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

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

@@ -0,0 +1,96 @@
+/**
+ * Types publics de `sonic-webgpu`.
+ * Glue DataProvider + SonicMediaRef (comme shader) ; `$mediaUrl` = helper jsonata côté expressions.
+ */
+
+/** Backend GPU actif (`auto` : ordre dépend du WGSL custom — voir `sonic-webgpu`). */
+export type SonicWebGpuBackendPrefer = "auto" | "webgpu" | "webgl2";
+export type SonicWebGpuBackend = "webgpu" | "webgl2" | "canvas2d";
+
+/** Noyau métier — `particles` = compute (ce qui démarque de sonic-shader). */
+export type SonicWebGpuKernel = "" | "image" | "particles";
+
+export type SonicWebGpuConfig = {
+  /** Corps WGSL : doit définir `fn mainImage(uv: vec2f, fragCoord: vec2f) -> vec4f`. */
+  shader?: string;
+  /**
+   * `particles` — simulation compute (défaut démo utile).
+   * `image` / `""` — passe fullscreen + canaux (proche shader).
+   */
+  kernel?: SonicWebGpuKernel;
+  /**
+   * `auto` (défaut) : meilleur backend dispo.
+   */
+  backend?: SonicWebGpuBackendPrefer;
+  channel0?: string;
+  channel1?: string;
+  channel2?: string;
+  channel3?: string;
+  play?: boolean;
+  mouse?: boolean;
+  releaseOffscreen?: boolean;
+  dprMax?: number;
+  param0?: number;
+  param1?: number;
+  param2?: number;
+  param3?: number;
+  /**
+   * Attracteur normalisé (0–1, origine haut-gauche) via dataProvider —
+   * tracking vidéo / landmarks → particules sans pointer.
+   */
+  targetX?: number;
+  targetY?: number;
+  dataProvider?: string;
+  outDataProvider?: string;
+  outInterval?: number;
+  /** Publie `frameUrl` + `snapshot` (SonicMediaRef) vers le out-DP. */
+  frameOut?: boolean;
+  aspectRatio?: string;
+};
+
+/** Sortie publiée / event `out`. */
+export type SonicWebGpuOutput = {
+  time: number;
+  frame: number;
+  mouseX: number;
+  mouseY: number;
+  hovering: boolean;
+  param0: number;
+  param1: number;
+  param2: number;
+  param3: number;
+  backend?: SonicWebGpuBackend;
+  /** ObjectURL du canvas (si `frame-out`). */
+  frameUrl?: string;
+  /** MediaRef du frame (si `frame-out`). */
+  snapshot?: {
+    url: string;
+    width: number;
+    height: number;
+    mime: string;
+  };
+};
+
+export class WebGpuCompileError extends Error {
+  constructor(
+    message: string,
+    public readonly infoLog?: string,
+  ) {
+    super(message);
+    this.name = "WebGpuCompileError";
+  }
+}
+
+export function parseBackendPrefer(
+  value: unknown,
+): SonicWebGpuBackendPrefer {
+  const s = String(value ?? "auto").trim().toLowerCase();
+  if (s === "webgpu" || s === "webgl2" || s === "auto") return s;
+  return "auto";
+}
+
+export function parseKernel(value: unknown): SonicWebGpuKernel {
+  const s = String(value ?? "").trim().toLowerCase();
+  if (s === "particles" || s === "image") return s;
+  return "";
+}

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

@@ -0,0 +1,75 @@
+# WebGPU
+
+`sonic-webgpu` — **GPU compute / effects** (companion to [`sonic-shader`](#core/components/functional/shader/shader.md/shader), not a clone).
+
+| | `sonic-shader` | `sonic-webgpu` |
+|--|--|--|
+| Role | ShaderToy GLSL, multipass image | **Compute** + useful kernels |
+| Demo | multipass / extract | **particles** (`kernel="particles"`) |
+| Glue | DP + MediaRef | **same glue** |
+
+Opt-in import:
+
+<sonic-code language="javascript">
+  <template>
+import "@supersoniks/concorde/webgpu";
+  </template>
+</sonic-code>
+
+Harris → patches → WebGPU mosaic: [Visual stack](#docs/_misc/visual-stack.md/visual-stack).
+
+## Demo — particles (compute)
+
+Simulation: `param0` = speed, `param1` = mouse attraction. WebGPU compute when available, otherwise CPU.
+
+<docs-lit-demo for="docs-webgpu-demo"></docs-lit-demo>
+
+## Kernels
+
+| `kernel` | Role |
+|----------|------|
+| `particles` | particle compute (storage buffer) — **useful demo case** |
+| `image` / empty | fullscreen WGSL pass + `channel0…3` (shader-like; WebGL2 fallback) |
+
+## Attributes
+
+| Attribute | Role |
+|-----------|------|
+| `kernel` | `particles` \| `image` |
+| `shader` | WGSL `mainImage` (image kernel, WebGPU) |
+| `backend` | `auto` \| `webgpu` \| `webgl2` |
+| `active-backend` | reflect |
+| `param0`…`param3` | floats (particles: speed / attraction) |
+| `targetX` / `targetY` | attractor 0–1 (DP, top-left origin) |
+| `channel0`…`channel3` | textures (image kernel) |
+| `dataProvider` | params / channels / `targetX`·`Y` |
+| `frame-out` | `frameUrl` + `snapshot` |
+| `play` / `mouse` | loop / pointer |
+
+## Markup particles
+
+<sonic-code language="html">
+  <template>
+&lt;sonic-webgpu
+  play
+  mouse
+  kernel="particles"
+  dataProvider="fx"
+&gt;&lt;/sonic-webgpu&gt;
+  </template>
+</sonic-code>
+
+## Chaining
+
+Same MediaRef / DP bridge as the rest of the stack. No live texture bus with `sonic-shader` (separate contexts).
+
+## CDN
+
+[`concorde-webgpu.bundle.js`](#docs/_getting-started/cdn-addons.md/cdn-addons) after the core.
+
+## Notes
+
+- Off viewport: **pause RAF** (no systematic destroy — that caused black frames + frozen particles on scroll).
+- Device destroy = disconnect / `kernel`|`backend` change.
+- Console: `[sonic-webgpu] backend: … kernel: …`
+- `backend="auto"` + WGSL `shader`: tries **WebGPU first** (otherwise the WebGL2 fallback ignores WGSL). Without `shader`, WebGL2 stays preferred.

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

@@ -0,0 +1,141 @@
+import { expect, describe, it, vi, beforeAll } from "vitest";
+import TestUtils from "@supersoniks/concorde/test-utils/TestUtils";
+import { buildWgslSource, DEFAULT_MAIN_IMAGE } from "./wgsl-prelude";
+import "./webgpu";
+import { SonicWebGpu } from "./webgpu";
+
+describe("buildWgslSource", () => {
+  it("injecte prelude + mainImage", () => {
+    const src = buildWgslSource(
+      "fn mainImage(uv: vec2f, fragCoord: vec2f) -> vec4f { _ = fragCoord; return iChannel0(uv); }",
+    );
+    expect(src).toContain("struct SonicUniforms");
+    expect(src).toContain("fn iChannel0");
+    expect(src).toContain("fn vs_main");
+    expect(src).toContain("fn fs_main");
+    expect(src).toContain("fn mainImage");
+  });
+
+  it("utilise le défaut si corps vide", () => {
+    const src = buildWgslSource("");
+    expect(src).toContain(DEFAULT_MAIN_IMAGE.slice(0, 20));
+  });
+
+  it("refuse un corps sans mainImage", () => {
+    expect(() => buildWgslSource("fn other() -> vec4f { return vec4f(1.0); }")).toThrow(
+      /mainImage/,
+    );
+  });
+});
+
+describe("sonic-webgpu", () => {
+  beforeAll(() => {
+    if (typeof globalThis.ResizeObserver === "undefined") {
+      globalThis.ResizeObserver = class {
+        observe() {}
+        unobserve() {}
+        disconnect() {}
+      } as typeof ResizeObserver;
+    }
+    if (typeof globalThis.IntersectionObserver === "undefined") {
+      globalThis.IntersectionObserver = class {
+        observe() {}
+        unobserve() {}
+        disconnect() {}
+        takeRecords() {
+          return [];
+        }
+        root = null;
+        rootMargin = "";
+        thresholds = [];
+      } as typeof IntersectionObserver;
+    }
+  });
+
+  it("enregistre le custom element", () => {
+    expect(customElements.get("sonic-webgpu")).toBe(SonicWebGpu);
+  });
+
+  it("applique param0…3 et canaux depuis dataProvider", async () => {
+    const { PublisherManager } = await import(
+      "@supersoniks/concorde/utils"
+    );
+    const id = "webgpu-form-test";
+    const pub = PublisherManager.get(id);
+    pub.set({
+      param0: 0.11,
+      param1: 0.22,
+      channel0: { url: "https://example.test/a.png" },
+      channel1: "https://example.test/b.png",
+    });
+    const el = TestUtils.bootstrap(
+      `<sonic-webgpu dataProvider="${id}"></sonic-webgpu>`,
+      true,
+    )[0] as SonicWebGpu;
+    await el.updateComplete;
+    await new Promise((r) => setTimeout(r, 0));
+    expect(el.param0).toBe(0.11);
+    expect(el.param1).toBe(0.22);
+    expect(el.channel0).toBe("https://example.test/a.png");
+    expect(el.channel1).toBe("https://example.test/b.png");
+
+    pub.param0.set(0.99);
+    await new Promise((r) => setTimeout(r, 0));
+    expect(el.param0).toBe(0.99);
+  });
+
+  it("lit targetX/targetY depuis dataProvider (tracking)", async () => {
+    const { PublisherManager } = await import(
+      "@supersoniks/concorde/utils"
+    );
+    const id = "webgpu-target-test";
+    const pub = PublisherManager.get(id);
+    pub.set({
+      param0: 0.4,
+      param1: 0.8,
+      targetX: 0.25,
+      targetY: 0.75,
+    });
+    const el = TestUtils.bootstrap(
+      `<sonic-webgpu dataProvider="${id}" kernel="particles" mouse="false"></sonic-webgpu>`,
+      true,
+    )[0] as SonicWebGpu;
+    await el.updateComplete;
+    await new Promise((r) => setTimeout(r, 0));
+    const data = pub.get() as { targetX?: number; targetY?: number };
+    expect(data.targetX).toBe(0.25);
+    expect(data.targetY).toBe(0.75);
+    expect(el.param0).toBe(0.4);
+    expect(el.param1).toBe(0.8);
+  });
+
+  it("émet error si aucun backend (sinon accepte canvas2d)", async () => {
+    const onError = vi.fn();
+    const el = TestUtils.bootstrap(
+      `<sonic-webgpu style="width:64px;height:64px"></sonic-webgpu>`,
+      true,
+    )[0] as SonicWebGpu;
+    el.addEventListener("error", onError);
+    el.shader =
+      "fn mainImage(uv: vec2f, fragCoord: vec2f) -> vec4f { _ = fragCoord; return vec4f(uv, 0.0, 1.0); }";
+    await el.updateComplete;
+    await new Promise((r) => setTimeout(r, 30));
+
+    if (onError.mock.calls.length > 0) {
+      expect(onError.mock.calls[0][0].detail.message).toMatch(
+        /WebGPU|WebGL2|Canvas2D/i,
+      );
+    } else {
+      // Environnement avec GPU : canvas monté
+      expect(el.shadowRoot?.querySelector("canvas")).toBeTruthy();
+      expect(["webgpu", "webgl2", "canvas2d"]).toContain(el.activeBackend);
+    }
+  });
+
+  it("parseBackendPrefer", async () => {
+    const { parseBackendPrefer } = await import("./types");
+    expect(parseBackendPrefer("auto")).toBe("auto");
+    expect(parseBackendPrefer("webgl2")).toBe("webgl2");
+    expect(parseBackendPrefer("nope")).toBe("auto");
+  });
+});