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

package/src/core/components/functional/3d/form-bind.ts

@@ -0,0 +1,40 @@
+import HTML from "@supersoniks/concorde/core/utils/HTML";
+import { asset } from "./asset";
+import {
+  formParams,
+  type FormBindHost,
+  type FormOrbit,
+} from "./form-params";
+
+export type { FormBindHost, FormOrbit };
+
+function resolveFormProviderId(
+  el: HTMLElement,
+  dataProvider: string,
+): string {
+  const own = dataProvider?.trim();
+  if (own) return own;
+  return (
+    HTML.getAncestorAttributeValue(el, "dataProvider") ||
+    HTML.getAncestorAttributeValue(el, "formDataProvider") ||
+    ""
+  );
+}
+
+function resolveOutProviderId(
+  el: HTMLElement,
+  outDataProvider: string,
+  dataProvider: string,
+): string {
+  const own = outDataProvider?.trim();
+  if (own) return own;
+  return resolveFormProviderId(el, dataProvider);
+}
+
+/** Form DP resolve + apply. Paths: `formBind.asset.*`, `formBind.formParams.*`. */
+export const formBind = {
+  resolveFormProviderId,
+  resolveOutProviderId,
+  asset,
+  formParams,
+} as const;

package/src/core/components/functional/3d/form-fields.ts

@@ -0,0 +1,80 @@
+import { parse } from "./parse";
+import { playback } from "./playback";
+import { reload } from "./reload";
+import type { FormBindHost } from "./form-params";
+
+/** Applique les scalaires / flags form → propriétés host. */
+function applyScalars(host: FormBindHost, data: Record<string, unknown>) {
+  if ("fov" in data) host.fov = parse.toNum(data.fov, host.fov);
+  if ("exposure" in data) {
+    host.exposure = parse.toNum(data.exposure, host.exposure);
+  }
+  if ("minDistance" in data) {
+    host.minDistance = parse.toNum(data.minDistance, host.minDistance);
+  }
+  if ("maxDistance" in data) {
+    host.maxDistance = parse.toNum(data.maxDistance, host.maxDistance);
+  }
+  if ("minPolar" in data) {
+    host.minPolar = parse.toNum(data.minPolar, host.minPolar);
+  }
+  if ("maxPolar" in data) {
+    host.maxPolar = parse.toNum(data.maxPolar, host.maxPolar);
+  }
+  if ("autoRotate" in data) {
+    host.autoRotate = parse.isFormFlagOn(data.autoRotate);
+  }
+  if ("camera" in data && typeof data.camera === "string") {
+    host.camera = parse.cameraMode(data.camera);
+  }
+}
+
+/** Asset / src → host ; retourne true si reload requis. */
+function applyAsset(
+  host: FormBindHost,
+  data: Record<string, unknown>,
+): boolean {
+  let reload = false;
+  if ("asset" in data) {
+    const a = parse.asset(data.asset);
+    if (a) {
+      host.asset = a;
+      reload = true;
+    }
+  }
+  if ("src" in data && typeof data.src === "string" && !("asset" in data)) {
+    if (host.src !== data.src) {
+      host.src = data.src;
+      reload = true;
+    }
+  }
+  return reload;
+}
+
+function orbitLimitsTouched(data: Record<string, unknown>): boolean {
+  return (
+    "minDistance" in data ||
+    "maxDistance" in data ||
+    "minPolar" in data ||
+    "maxPolar" in data ||
+    "camera" in data
+  );
+}
+
+/** Pousse les champs déjà appliqués vers le runtime live. */
+function pushToRuntime(host: FormBindHost, data: Record<string, unknown>) {
+  if (!host.runtime) return;
+  if ("exposure" in data) host.runtime.setExposure(host.exposure);
+  if ("fov" in data) host.runtime.setFov(host.fov);
+  if ("camera" in data) {
+    host.runtime.applyCameraMode(parse.cameraMode(host.camera));
+  }
+  if (orbitLimitsTouched(data)) reload.applyOrbitLimits(host as never);
+  if ("autoRotate" in data) playback.syncAutoRotate(host as never);
+}
+
+export const formFields = {
+  applyScalars,
+  applyAsset,
+  pushToRuntime,
+} as const;

package/src/core/components/functional/3d/form-params.ts

@@ -0,0 +1,97 @@
+import { ORBIT_CHANGE_EPSILON } from "./constants";
+import { formFields } from "./form-fields";
+import { parse } from "./parse";
+import { playback } from "./playback";
+import { reload } from "./reload";
+import type { SceneRuntime } from "./runtime";
+import type { Sonic3dAsset, Sonic3dCameraMode } from "./types";
+
+export type FormOrbit = { yaw: number; pitch: number; distance: number };
+
+/** Host minimal pour appliquer les champs form → viewer. */
+export type FormBindHost = {
+  fov: number;
+  exposure: number;
+  minDistance: number;
+  maxDistance: number;
+  minPolar: number;
+  maxPolar: number;
+  autoRotate: boolean;
+  camera: Sonic3dCameraMode;
+  asset: Sonic3dAsset | null;
+  src: string;
+  runtime: SceneRuntime | null;
+  frame: number;
+  hovering: boolean;
+  pointerX: number;
+  pointerY: number;
+  lastFormOrbit: FormOrbit | null;
+};
+
+function orbitChanged(prev: FormOrbit | null, next: FormOrbit): boolean {
+  if (!prev) return true;
+  return (
+    Math.abs(prev.yaw - next.yaw) > ORBIT_CHANGE_EPSILON ||
+    Math.abs(prev.pitch - next.pitch) > ORBIT_CHANGE_EPSILON ||
+    Math.abs(prev.distance - next.distance) > ORBIT_CHANGE_EPSILON
+  );
+}
+
+/**
+ * Orbit depuis le form : uniquement si yaw/pitch/distance ont changé
+ * (sinon chaque mutation télémétrie / checkbox réapplique et combat autoRotate).
+ */
+function readOrbit(
+  host: FormBindHost,
+  data: Record<string, unknown>,
+): FormOrbit {
+  const cur = host.runtime!.snapshot({
+    time: 0,
+    frame: host.frame,
+    hovering: host.hovering ? 1 : 0,
+    pointerX: host.pointerX,
+    pointerY: host.pointerY,
+  });
+  return {
+    yaw: "yaw" in data ? parse.toNum(data.yaw, cur.yaw) : cur.yaw,
+    pitch: "pitch" in data ? parse.toNum(data.pitch, cur.pitch) : cur.pitch,
+    distance:
+      "distance" in data
+        ? parse.toNum(data.distance, cur.distance)
+        : cur.distance,
+  };
+}
+
+function applyFormOrbit(host: FormBindHost, data: Record<string, unknown>) {
+  if (!host.runtime) return;
+  if (!("distance" in data || "yaw" in data || "pitch" in data)) return;
+  const next = readOrbit(host, data);
+  const prev = host.lastFormOrbit;
+  if (!orbitChanged(prev, next)) return;
+  host.lastFormOrbit = next;
+  if (host.autoRotate && prev) {
+    host.autoRotate = false;
+    playback.syncAutoRotate(host as never);
+  }
+  host.runtime.setOrbitSpherical(next.yaw, next.pitch, next.distance);
+  host.runtime.render();
+}
+
+/**
+ * Auto-bind form → viewer : champs `FORM_CONTROL_KEYS` sur le DP / form ancêtre.
+ */
+function applyFormParams(host: FormBindHost, data: Record<string, unknown>) {
+  formFields.applyScalars(host, data);
+  const needReload = formFields.applyAsset(host, data);
+
+  if (!host.runtime) {
+    if (needReload) void reload.run(host as never);
+    return;
+  }
+
+  formFields.pushToRuntime(host, data);
+  applyFormOrbit(host, data);
+  if (needReload) void reload.run(host as never);
+}
+
+export const formParams = { applyFormParams, applyFormOrbit } as const;

package/src/core/components/functional/3d/frame-capture.spec.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { DEFAULT_SNAPSHOT_INTERVAL_MS } from "./constants";
+import { frameCapture, type FrameCaptureHost } from "./frame-capture";
+
+function makeHost(
+  overrides: Partial<FrameCaptureHost> = {},
+): FrameCaptureHost {
+  return {
+    outPublisher: null,
+    runtime: null,
+    snapshotInterval: DEFAULT_SNAPSHOT_INTERVAL_MS,
+    frameOut: false,
+    snapshotBusy: false,
+    lastSnapshotAt: 0,
+    frameUrls: [],
+    snapshotSeq: 0,
+    ...overrides,
+  };
+}
+
+describe("frameCapture.wantsFrameCapture", () => {
+  beforeEach(() => {
+    URL.createObjectURL = vi.fn(() => "blob:x") as typeof URL.createObjectURL;
+    URL.revokeObjectURL = vi.fn() as typeof URL.revokeObjectURL;
+  });
+
+  it("exige un outPublisher", () => {
+    expect(
+      frameCapture.wantsFrameCapture(makeHost({ frameOut: true })),
+    ).toBe(false);
+  });
+
+  it("active avec frameOut", () => {
+    expect(
+      frameCapture.wantsFrameCapture(
+        makeHost({ outPublisher: {}, frameOut: true }),
+      ),
+    ).toBe(true);
+  });
+
+  it("active si listener sur frameUrl", () => {
+    const proxies = new Map([["frameUrl", { hasListener: () => true }]]);
+    expect(
+      frameCapture.wantsFrameCapture(
+        makeHost({
+          outPublisher: { _proxies_: proxies },
+          frameOut: false,
+        }),
+      ),
+    ).toBe(true);
+  });
+});
+
+describe("frameCapture.revokeAll", () => {
+  it("révoque les urls et invalide la séquence", () => {
+    const revoke = vi.fn();
+    URL.revokeObjectURL = revoke as typeof URL.revokeObjectURL;
+    const host = makeHost({
+      outPublisher: {},
+      frameOut: true,
+      snapshotBusy: true,
+      lastSnapshotAt: 1,
+      frameUrls: ["blob:a", "blob:b"],
+      snapshotSeq: 3,
+    });
+    frameCapture.revokeAll(host);
+    expect(revoke).toHaveBeenCalledTimes(2);
+    expect(host.frameUrls).toEqual([]);
+    expect(host.snapshotBusy).toBe(false);
+    expect(host.snapshotSeq).toBe(4);
+  });
+});

package/src/core/components/functional/3d/frame-capture.ts

@@ -0,0 +1,135 @@
+import { revokeMediaUrls } from "@supersoniks/concorde/core/utils/mediaRef";
+import {
+  DEFAULT_SNAPSHOT_INTERVAL_MS,
+  MIN_SNAPSHOT_INTERVAL_MS,
+  SNAPSHOT_JPEG_MIME,
+  SNAPSHOT_JPEG_QUALITY,
+} from "./constants";
+import { publisherFieldHasListener } from "./publisher-listen";
+import type { Sonic3dSnapshot } from "./types";
+
+export type FrameCaptureHost = {
+  outPublisher: {
+    _proxies_?: Map<string, { hasListener?: () => boolean }>;
+  } | null;
+  runtime: {
+    renderer: { domElement: HTMLCanvasElement };
+  } | null;
+  snapshotInterval: number;
+  frameOut: boolean;
+  snapshotBusy: boolean;
+  lastSnapshotAt: number;
+  frameUrls: string[];
+  snapshotSeq: number;
+};
+
+const FRAME_KEYS = ["frameUrl", "snapshot"] as const;
+
+function wantsFrameCapture(host: FrameCaptureHost): boolean {
+  if (!host.outPublisher) return false;
+  if (host.frameOut) return true;
+  for (const key of FRAME_KEYS) {
+    if (publisherFieldHasListener(host.outPublisher, key)) return true;
+  }
+  return false;
+}
+
+function mediaFromBlob(
+  canvas: HTMLCanvasElement,
+  blob: Blob,
+): Sonic3dSnapshot {
+  const url = URL.createObjectURL(blob);
+  return {
+    url,
+    blob,
+    width: canvas.width,
+    height: canvas.height,
+    mime: blob.type || SNAPSHOT_JPEG_MIME,
+  };
+}
+
+function canvasToMedia(
+  canvas: HTMLCanvasElement,
+): Promise<Sonic3dSnapshot | null> {
+  return new Promise((resolve) => {
+    if (typeof canvas.toBlob !== "function") {
+      resolve(null);
+      return;
+    }
+    const onBlob = (blob: Blob | null) => {
+      if (!blob) {
+        resolve(null);
+        return;
+      }
+      resolve(mediaFromBlob(canvas, blob));
+    };
+    try {
+      canvas.toBlob(onBlob, SNAPSHOT_JPEG_MIME, SNAPSHOT_JPEG_QUALITY);
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+function writeFrameFields(host: FrameCaptureHost, media: Sonic3dSnapshot) {
+  const pub = host.outPublisher as Record<
+    string,
+    { set: (v: unknown) => void }
+  > | null;
+  if (!pub) return;
+  try {
+    pub.frameUrl.set(media.url);
+  } catch {
+    /* leaf manquant */
+  }
+  try {
+    pub.snapshot.set(media);
+  } catch {
+    /* leaf manquant */
+  }
+}
+
+/**
+ * Si un consommateur écoute `frameUrl` / `snapshot`, capture le canvas
+ * (throttlé, async). Révoque l’ObjectURL précédent.
+ */
+function maybeCapture(host: FrameCaptureHost, now: number) {
+  if (host.snapshotBusy) return;
+  if (!host.runtime) return;
+  if (!wantsFrameCapture(host)) return;
+  const interval = Math.max(
+    MIN_SNAPSHOT_INTERVAL_MS,
+    Number.isFinite(host.snapshotInterval) && host.snapshotInterval > 0
+      ? host.snapshotInterval
+      : DEFAULT_SNAPSHOT_INTERVAL_MS,
+  );
+  if (now - host.lastSnapshotAt < interval) return;
+  host.lastSnapshotAt = now;
+  host.snapshotBusy = true;
+  const seq = ++host.snapshotSeq;
+  const canvas = host.runtime.renderer.domElement;
+  void canvasToMedia(canvas).then((media) => {
+    host.snapshotBusy = false;
+    if (!media || seq !== host.snapshotSeq) {
+      if (media) revokeMediaUrls([media.url]);
+      return;
+    }
+    revokeMediaUrls(host.frameUrls);
+    host.frameUrls = [media.url];
+    writeFrameFields(host, media);
+  });
+}
+
+function revokeAll(host: FrameCaptureHost) {
+  host.snapshotSeq++;
+  host.snapshotBusy = false;
+  revokeMediaUrls(host.frameUrls);
+  host.frameUrls = [];
+}
+
+export const frameCapture = {
+  wantsFrameCapture,
+  maybeCapture,
+  revokeAll,
+  FRAME_KEYS,
+} as const;

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

@@ -0,0 +1,35 @@
+import * as THREE from "three";
+
+const WEBGL_UNAVAILABLE_MSG =
+  "WebGL indisponible — sonic-3d nécessite WebGL.";
+
+/** Crée un WebGLRenderer ou lève si WebGL indisponible (jsdom / GPU). */
+export function createRenderer(canvas: HTMLCanvasElement): THREE.WebGLRenderer {
+  const probe = document.createElement("canvas");
+  const gl = probe.getContext("webgl2") || probe.getContext("webgl");
+  if (!gl || typeof (gl as WebGLRenderingContext).getParameter !== "function") {
+    throw new Error(WEBGL_UNAVAILABLE_MSG);
+  }
+  const rendererOpts = {
+    canvas,
+    antialias: true,
+    alpha: false,
+    /**
+     * Requis pour `toBlob` / snapshot async après `render()` (pont shader via DP).
+     */
+    preserveDrawingBuffer: true,
+    powerPreference: "high-performance" as const,
+  };
+  let renderer: THREE.WebGLRenderer;
+  try {
+    renderer = new THREE.WebGLRenderer(rendererOpts);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`${WEBGL_UNAVAILABLE_MSG} (${msg})`);
+  }
+  if (!renderer.getContext()) {
+    renderer.dispose();
+    throw new Error(WEBGL_UNAVAILABLE_MSG);
+  }
+  return renderer;
+}

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

@@ -0,0 +1,101 @@
+import { PublisherManager } from "@supersoniks/concorde/utils";
+import { ensure } from "./ensure";
+import { formBind } from "./form-bind";
+import type { SceneRuntime } from "./runtime";
+
+/** Host Lit pour cycle de vie / observers / bind DP. */
+export type LifeHost = {
+  aspectRatio: string;
+  dataProvider: string;
+  outDataProvider: string;
+  releaseOffscreen: boolean;
+  inView: boolean;
+  runtime: SceneRuntime | null;
+  camera: string;
+  fov: number;
+  exposure: number;
+  dprMax: number;
+  fit: boolean;
+  minDistance: number;
+  maxDistance: number;
+  minPolar: number;
+  maxPolar: number;
+  style: CSSStyleDeclaration;
+  formPublisher: ReturnType<typeof PublisherManager.get> | null;
+  outPublisher: ReturnType<typeof PublisherManager.get> | null;
+  resizeObserver: ResizeObserver | null;
+  intersectionObserver: IntersectionObserver | null;
+  onFormMutation: () => void;
+  syncPlayback: () => void;
+};
+
+function applyAspectRatio(host: LifeHost) {
+  const forced = host.aspectRatio.trim();
+  if (forced) {
+    host.style.setProperty(
+      "--sonic-3d-ar",
+      forced.includes("/") ? forced : forced.replace(":", " / "),
+    );
+    return;
+  }
+  host.style.removeProperty("--sonic-3d-ar");
+}
+
+function unbindFormProvider(host: LifeHost) {
+  if (host.formPublisher) {
+    host.formPublisher.offInternalMutation(host.onFormMutation);
+    host.formPublisher = null;
+  }
+}
+
+function bindFormProvider(host: LifeHost) {
+  unbindFormProvider(host);
+  const id = formBind.resolveFormProviderId(
+    host as unknown as HTMLElement,
+    host.dataProvider,
+  );
+  if (!id) return;
+  host.formPublisher = PublisherManager.get(id);
+  host.formPublisher.onInternalMutation(host.onFormMutation);
+  host.onFormMutation();
+}
+
+function bindOutPublisher(host: LifeHost) {
+  const id = formBind.resolveOutProviderId(
+    host as unknown as HTMLElement,
+    host.outDataProvider,
+    host.dataProvider,
+  );
+  host.outPublisher = id ? PublisherManager.get(id) : null;
+}
+
+function firstUpdated(host: LifeHost) {
+  applyAspectRatio(host);
+  host.resizeObserver = new ResizeObserver(() =>
+    ensure.syncSize(host as never),
+  );
+  host.resizeObserver.observe(host as unknown as Element);
+  host.intersectionObserver = new IntersectionObserver(
+    (entries) => {
+      host.inView = entries.some((e) => e.isIntersecting);
+      ensure.syncVisibility(host as never);
+    },
+    { threshold: 0 },
+  );
+  host.intersectionObserver.observe(host as unknown as Element);
+  bindFormProvider(host);
+  bindOutPublisher(host);
+  requestAnimationFrame(() => {
+    if (host.inView || !host.releaseOffscreen) {
+      void ensure.ensureRuntime(host as never);
+    }
+  });
+}
+
+export const life = {
+  applyAspectRatio,
+  unbindFormProvider,
+  bindFormProvider,
+  bindOutPublisher,
+  firstUpdated,
+} as const;

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

@@ -0,0 +1,129 @@
+import * as THREE from "three";
+import type { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { parse } from "./parse";
+import type { Sonic3dAsset } from "./types";
+import { demoContent } from "./demo-content";
+import { pick, type HighlightCtx } from "./pick";
+
+export type LoadCtx = HighlightCtx & {
+  root: THREE.Group;
+  content: THREE.Object3D | null;
+  bbox: THREE.Box3;
+  blobUrl: string | null;
+  loader: GLTFLoader;
+  fitEnabled: boolean;
+  fitToContent: () => void;
+};
+
+function revokeBlob(ctx: { blobUrl: string | null }) {
+  if (ctx.blobUrl) {
+    try {
+      URL.revokeObjectURL(ctx.blobUrl);
+    } catch {
+      /* ignore */
+    }
+    ctx.blobUrl = null;
+  }
+}
+
+function clearContent(ctx: LoadCtx) {
+  pick.clearHighlight(ctx);
+  if (!ctx.content) return;
+  ctx.root.remove(ctx.content);
+  ctx.content.traverse((obj: THREE.Object3D) => {
+    const mesh = obj as THREE.Mesh;
+    if (mesh.isMesh) {
+      mesh.geometry?.dispose();
+      const mats = Array.isArray(mesh.material)
+        ? mesh.material
+        : [mesh.material];
+      for (const m of mats) m?.dispose?.();
+    }
+  });
+  ctx.content = null;
+  ctx.bbox.makeEmpty();
+}
+
+function updateBBox(ctx: LoadCtx) {
+  ctx.bbox.makeEmpty();
+  if (ctx.content) ctx.bbox.setFromObject(ctx.content);
+}
+
+function applyMorphTargets(
+  root: THREE.Object3D,
+  weights: Record<string, number>,
+) {
+  root.traverse((obj: THREE.Object3D) => {
+    const mesh = obj as THREE.Mesh;
+    if (!mesh.isMesh || !mesh.morphTargetDictionary || !mesh.morphTargetInfluences)
+      return;
+    for (const [name, w] of Object.entries(weights)) {
+      const idx = mesh.morphTargetDictionary[name];
+      if (idx !== undefined) {
+        mesh.morphTargetInfluences[idx] = w;
+      }
+    }
+  });
+}
+
+/**
+ * Charge un asset (URL / blob) ou affiche le cube de démo si vide.
+ * Retourne `{ ready, error }` ; lève si load échoue après fallback démo.
+ */
+async function asset(
+  ctx: LoadCtx,
+  asset: Sonic3dAsset | null,
+  token: number,
+  isCurrent: (t: number) => boolean,
+): Promise<{ ready: boolean; error: string | null }> {
+  clearContent(ctx);
+
+  try {
+    let url = asset?.url?.trim() ?? "";
+    if (!url && asset?.blob) {
+      revokeBlob(ctx);
+      ctx.blobUrl = URL.createObjectURL(asset.blob);
+      url = ctx.blobUrl;
+    }
+
+    if (!url) {
+      ctx.content = demoContent.create();
+      ctx.root.add(ctx.content);
+    } else {
+      const kind = asset?.kind ?? parse.guessKind(url);
+      if (kind === "obj" || kind === "ply") {
+        throw new Error(
+          `Format "${kind}" non supporté en V1 — utilisez glTF/GLB.`,
+        );
+      }
+      const gltf = await ctx.loader.loadAsync(url);
+      if (!isCurrent(token)) return { ready: false, error: null };
+      ctx.content = gltf.scene;
+      ctx.root.add(ctx.content);
+      if (asset?.morphTargets) {
+        applyMorphTargets(ctx.content, asset.morphTargets);
+      }
+    }
+
+    if (!isCurrent(token)) return { ready: false, error: null };
+    updateBBox(ctx);
+    if (ctx.fitEnabled) ctx.fitToContent();
+    return { ready: true, error: null };
+  } catch (err) {
+    if (!isCurrent(token)) return { ready: false, error: null };
+    const error = err instanceof Error ? err.message : String(err);
+    ctx.content = demoContent.create();
+    ctx.root.add(ctx.content);
+    updateBBox(ctx);
+    if (ctx.fitEnabled) ctx.fitToContent();
+    throw err instanceof Error ? err : new Error(error);
+  }
+}
+
+export const load = {
+  asset,
+  applyMorphTargets,
+  clearContent,
+  updateBBox,
+  revokeBlob,
+} as const;