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

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

@@ -0,0 +1,171 @@
+import { expect, describe, it, afterEach, beforeAll } from "vitest";
+import TestUtils from "@supersoniks/concorde/test-utils/TestUtils";
+import type { OrbitControls } from "three/addons/controls/OrbitControls.js";
+import { Sonic3dCameraMode } from "./constants";
+import { orbit } from "./orbit";
+import { parse } from "./parse";
+import "./3d";
+import { Sonic3d } from "./3d";
+
+describe("parseCameraMode", () => {
+  it("accepte orbit / perspective / ortho", () => {
+    expect(parse.cameraMode("orbit")).toBe(Sonic3dCameraMode.Orbit);
+    expect(parse.cameraMode("PERSPECTIVE")).toBe(Sonic3dCameraMode.Perspective);
+    expect(parse.cameraMode("ortho")).toBe(Sonic3dCameraMode.Ortho);
+    expect(parse.cameraMode("nope")).toBe(Sonic3dCameraMode.Orbit);
+    expect(parse.cameraMode("")).toBe(Sonic3dCameraMode.Orbit);
+  });
+});
+
+describe("guessKind / parseAsset", () => {
+  it("détecte l’extension", () => {
+    expect(parse.guessKind("/a/model.glb")).toBe("glb");
+    expect(parse.guessKind("https://x/y.gltf?v=1")).toBe("gltf");
+    expect(parse.guessKind("/mesh.obj")).toBe("obj");
+    expect(parse.guessKind("/x.bin")).toBe("url");
+  });
+
+  it("parse string et objet", () => {
+    expect(parse.asset("/m.glb")).toEqual({ kind: "glb", url: "/m.glb" });
+    expect(parse.asset({ url: "/a.gltf", kind: "gltf" })).toEqual({
+      kind: "gltf",
+      url: "/a.gltf",
+    });
+    expect(parse.asset(null)).toBeNull();
+    expect(parse.asset({})).toBeNull();
+  });
+
+  it("accepte un Blob", () => {
+    const blob = new Blob([new Uint8Array([1, 2, 3])], {
+      type: "model/gltf-binary",
+    });
+    const a = parse.asset({ blob, kind: "glb" });
+    expect(a?.blob).toBe(blob);
+    expect(a?.kind).toBe("glb");
+  });
+});
+
+describe("toNum / isFormFlagOn", () => {
+  it("coerce nombre / string", () => {
+    expect(parse.toNum(3, 0)).toBe(3);
+    expect(parse.toNum("2.5", 0)).toBe(2.5);
+    expect(parse.toNum("x", 7)).toBe(7);
+  });
+
+  it("flag form checkbox unique", () => {
+    expect(parse.isFormFlagOn("true")).toBe(true);
+    expect(parse.isFormFlagOn(null)).toBe(false);
+    expect(parse.isFormFlagOn("false")).toBe(false);
+    expect(parse.isFormFlagOn(1)).toBe(true);
+    expect(parse.isFormFlagOn("on")).toBe(true);
+  });
+});
+
+describe("Sonic3d", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  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-3d")).toBe(Sonic3d);
+  });
+
+  it("monte sans src (cube démo) et expose les attributs", async () => {
+    const el = TestUtils.bootstrap(
+      `<sonic-3d camera="perspective" fov="50" aspect-ratio="1"></sonic-3d>`,
+    )[0] as Sonic3d;
+    expect(el.camera).toBe(Sonic3dCameraMode.Perspective);
+    expect(el.fov).toBe(50);
+    expect(el.tagName.toLowerCase()).toBe("sonic-3d");
+    await el.updateComplete;
+  });
+
+  it("reste stable sans WebGL (jsdom)", async () => {
+    const el = TestUtils.bootstrap(
+      `<sonic-3d style="width:64px;height:64px"></sonic-3d>`,
+    )[0] as Sonic3d;
+    await new Promise((r) => setTimeout(r, 50));
+    await el.updateComplete;
+    expect(el).toBeInstanceOf(Sonic3d);
+  });
+});
+
+describe("orbit.wheelAffectsZoom", () => {
+  const mockControls = (opts: {
+    distance: number;
+    minDistance?: number;
+    maxDistance?: number;
+    orthographic?: boolean;
+    zoom?: number;
+    minZoom?: number;
+    maxZoom?: number;
+  }) =>
+    ({
+      minDistance: opts.minDistance ?? 1,
+      maxDistance: opts.maxDistance ?? 10,
+      minZoom: opts.minZoom ?? 0,
+      maxZoom: opts.maxZoom ?? Infinity,
+      getDistance: () => opts.distance,
+      object: opts.orthographic
+        ? { isOrthographicCamera: true, zoom: opts.zoom ?? 1 }
+        : { isPerspectiveCamera: true },
+    }) as unknown as OrbitControls;
+
+  it("perspective : bloque aux bornes dans le sens demandé", () => {
+    const atMin = mockControls({ distance: 1, minDistance: 1, maxDistance: 10 });
+    expect(orbit.wheelAffectsZoom(atMin, -1)).toBe(false);
+    expect(orbit.wheelAffectsZoom(atMin, 1)).toBe(true);
+
+    const atMax = mockControls({
+      distance: 10,
+      minDistance: 1,
+      maxDistance: 10,
+    });
+    expect(orbit.wheelAffectsZoom(atMax, 1)).toBe(false);
+    expect(orbit.wheelAffectsZoom(atMax, -1)).toBe(true);
+  });
+
+  it("perspective : maxDistance infini laisse zoom out", () => {
+    const c = mockControls({
+      distance: 1000,
+      minDistance: 1,
+      maxDistance: Infinity,
+    });
+    expect(orbit.wheelAffectsZoom(c, 1)).toBe(true);
+  });
+
+  it("ortho : bornes minZoom / maxZoom", () => {
+    const atMaxZoom = mockControls({
+      distance: 5,
+      orthographic: true,
+      zoom: 4,
+      maxZoom: 4,
+      minZoom: 0.5,
+    });
+    expect(orbit.wheelAffectsZoom(atMaxZoom, -1)).toBe(false);
+    expect(orbit.wheelAffectsZoom(atMaxZoom, 1)).toBe(true);
+  });
+});

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

@@ -0,0 +1,186 @@
+import { html } from "lit";
+import { customElement, state } from "lit/decorators.js";
+import { PublisherManager } from "@supersoniks/concorde/utils";
+import { formBind, type FormOrbit } from "./form-bind";
+import { life } from "./life";
+import { outPublish } from "./out-publish";
+import type { SceneHit } from "./pick";
+import { playback } from "./playback";
+import { pointer } from "./pointer";
+import { Sonic3dProps } from "./props";
+import type { SceneRuntime } from "./scene-runtime";
+import { sonic3dStyles } from "./styles";
+import { propUpdate } from "./updated";
+import { wire } from "./wire";
+
+/**
+ * Viewer 3D Concorde (Three.js) — glTF/GLB, caméra orbit/perspective/ortho,
+ * outputs dataProvider paresseux. Opt-in : `@supersoniks/concorde/3d`.
+ */
+@customElement("sonic-3d")
+export class Sonic3d extends Sonic3dProps {
+  static styles = sonic3dStyles;
+
+  @state() private errorMessage = "";
+
+  /** État runtime partagé avec les helpers (lu ici pour noUnusedLocals). */
+  runtime: SceneRuntime | null = null;
+  raf = 0;
+  startTime = 0;
+  frame = 0;
+  hovering = false;
+  pointerX = 0.5;
+  pointerY = 0.5;
+  lastHit: SceneHit | null = null;
+  outEventListeners = 0;
+  inView = true;
+  ready = false;
+  releasing = false;
+  loadToken = 0;
+  resizeObserver: ResizeObserver | null = null;
+  intersectionObserver: IntersectionObserver | null = null;
+  formPublisher: ReturnType<typeof PublisherManager.get> | null = null;
+  outPublisher: ReturnType<typeof PublisherManager.get> | null = null;
+  lastOutAt = 0;
+  lastSnapshotAt = 0;
+  snapshotBusy = false;
+  frameUrls: string[] = [];
+  snapshotSeq = 0;
+  /** Contrat SonicFrameSource — incrémenté après chaque render. */
+  frameSeq = 0;
+  lastFormOrbit: FormOrbit | null = null;
+
+  onFormMutation = () => {
+    const data = (this.formPublisher?.get() ?? {}) as Record<string, unknown>;
+    formBind.formParams.applyFormParams(this as never, data);
+  };
+
+  connectedCallback() {
+    super.connectedCallback();
+    // Lectures groupées : champs mutés via helpers (noUnusedLocals).
+    void [
+      this.pointerX,
+      this.pointerY,
+      this.lastHit,
+      this.inView,
+      this.releasing,
+      this.loadToken,
+      this.resizeObserver,
+      this.intersectionObserver,
+      this.formPublisher,
+      this.outPublisher,
+      this.lastOutAt,
+      this.lastSnapshotAt,
+      this.snapshotBusy,
+      this.frameUrls,
+      this.snapshotSeq,
+      this.lastFormOrbit,
+      this.syncAutoRotate,
+      this.syncPlayback,
+      this.bindOutPublisher,
+      this.onPointerMove,
+      this.onPointerDown,
+      this.onDblClick,
+      this.onPointerEnter,
+      this.onPointerLeave,
+      this.onFormMutation,
+      this.errorMessage,
+    ];
+    wire.connect(this as never);
+  }
+
+  override addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject | null,
+    options?: boolean | AddEventListenerOptions,
+  ): void {
+    if (type === "out" && listener) this.outEventListeners++;
+    super.addEventListener(type, listener as never, options);
+  }
+
+  override removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject | null,
+    options?: boolean | EventListenerOptions,
+  ): void {
+    if (type === "out" && listener) {
+      this.outEventListeners = Math.max(0, this.outEventListeners - 1);
+    }
+    super.removeEventListener(type, listener as never, options);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    wire.disconnect(this as never);
+  }
+
+  protected firstUpdated() {
+    life.firstUpdated(this as never);
+  }
+
+  protected updated(changed: Map<string | number | symbol, unknown>) {
+    propUpdate.updated(this as never, changed);
+  }
+
+  syncAutoRotate = () => playback.syncAutoRotate(this as never);
+  syncPlayback = () => playback.syncPlayback(this as never, this.loop);
+  bindOutPublisher = () => life.bindOutPublisher(this as never);
+
+  private loop = () => {
+    this.raf = requestAnimationFrame(this.loop);
+    this.drawFrame(performance.now());
+    if (this.playOnHover && !this.hovering && !this.autoRotate) {
+      playback.stopLoop(this as never);
+    }
+  };
+
+  private drawFrame(now: number) {
+    if (!this.runtime || !this.ready) return;
+    this.frame++;
+    this.runtime.render();
+    this.frameSeq++;
+    outPublish.maybePublish(this as never, now, (now - this.startTime) / 1000);
+  }
+
+  /** Contrat SonicFrameSource — canvas Three (preserveDrawingBuffer). */
+  getFrameCanvas(): HTMLCanvasElement | null {
+    if (!this.runtime || !this.ready) return null;
+    return this.runtime.renderer.domElement;
+  }
+
+  onPointerMove = (e: PointerEvent) => pointer.onMove(this as never, e);
+  onPointerDown = (e: PointerEvent) => pointer.onDown(this as never, e);
+  onDblClick = () => pointer.onDblClick(this as never);
+  onPointerEnter = () => pointer.onEnter(this as never);
+  onPointerLeave = () => pointer.onLeave(this as never);
+
+  render() {
+    return html`
+      <canvas part="canvas"></canvas>
+      ${this.errorMessage
+        ? html`<div class="err" part="error">${this.errorMessage}</div>`
+        : null}
+    `;
+  }
+}
+
+export { Sonic3dCameraMode } from "./constants";
+export type {
+  Sonic3dAsset,
+  Sonic3dConfig,
+  Sonic3dOutput,
+} from "./types";
+export type { SonicMediaRef, SonicFrameSource } from "@supersoniks/concorde/core/utils/mediaRef";
+export {
+  toMediaUrl,
+  cloneMediaRef,
+  isFrameSource,
+} from "@supersoniks/concorde/core/utils/mediaRef";
+export { frameCapture } from "./frame-capture";
+export { frameSource } from "./frame-source";
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "sonic-3d": Sonic3d;
+  }
+}

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

@@ -0,0 +1,22 @@
+import { PublisherManager } from "@supersoniks/concorde/utils";
+import { parse } from "./parse";
+import type { Sonic3dAsset } from "./types";
+
+/** Résout asset prioritaire : prop → src → DP. */
+function resolve(
+  host: { asset: Sonic3dAsset | null; src: string },
+  formPublisher: ReturnType<typeof PublisherManager.get> | null,
+): Sonic3dAsset | null {
+  if (host.asset?.url || host.asset?.blob) return host.asset;
+  const fromSrc = parse.asset(host.src);
+  if (fromSrc) return fromSrc;
+  const data = (formPublisher?.get() ?? {}) as Record<string, unknown>;
+  if ("asset" in data) {
+    const a = parse.asset(data.asset);
+    if (a) return a;
+  }
+  if ("src" in data) return parse.asset(data.src);
+  return null;
+}
+
+export const asset = { resolve } as const;

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

@@ -0,0 +1,77 @@
+import * as THREE from "three";
+import {
+  DEFAULT_EXPOSURE,
+  DEFAULT_FOV,
+  DEFAULT_MAX_DISTANCE,
+  DEFAULT_MIN_DISTANCE,
+  DEFAULT_MIN_POLAR_RAD,
+  Sonic3dCameraMode,
+} from "./constants";
+import { demoContent } from "./demo-content";
+import { createRenderer } from "./gl";
+import type { OrbitLimits } from "./orbit";
+import type { SceneRuntimeOptions } from "./opts";
+
+export type BootedScene = {
+  scene: THREE.Scene;
+  renderer: THREE.WebGLRenderer;
+  canvas: HTMLCanvasElement;
+  perspCam: THREE.PerspectiveCamera;
+  orthoCam: THREE.OrthographicCamera;
+  activeCam: THREE.Camera;
+  root: THREE.Group;
+  lights: THREE.Light[];
+  dprMax: number;
+  mode: Sonic3dCameraMode;
+  fov: number;
+  fitEnabled: boolean;
+  limits: OrbitLimits;
+  autoRotate: boolean;
+};
+
+/** Alloue scène / caméras / renderer / lumières (sans OrbitControls). */
+export function bootScene(opts: SceneRuntimeOptions): BootedScene {
+  const dprMax = opts.dprMax ?? 2;
+  const mode = opts.camera ?? Sonic3dCameraMode.Orbit;
+  const fov = opts.fov ?? DEFAULT_FOV;
+  const fitEnabled = opts.fit !== false;
+  const limits: OrbitLimits = {
+    minDistance: opts.minDistance ?? DEFAULT_MIN_DISTANCE,
+    maxDistance: opts.maxDistance ?? DEFAULT_MAX_DISTANCE,
+    minPolar: opts.minPolar ?? DEFAULT_MIN_POLAR_RAD,
+    maxPolar: opts.maxPolar ?? Math.PI - DEFAULT_MIN_POLAR_RAD,
+  };
+
+  const scene = new THREE.Scene();
+  scene.background = new THREE.Color(0x0a0a0a);
+  const root = new THREE.Group();
+  scene.add(root);
+
+  const perspCam = new THREE.PerspectiveCamera(fov, 1, 0.01, 2000);
+  perspCam.position.set(2.2, 1.6, 2.8);
+  const orthoCam = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.01, 2000);
+  orthoCam.position.set(2.2, 1.6, 2.8);
+
+  const renderer = createRenderer(opts.canvas);
+  renderer.outputColorSpace = THREE.SRGBColorSpace;
+  renderer.toneMapping = THREE.ACESFilmicToneMapping;
+  renderer.toneMappingExposure = opts.exposure ?? DEFAULT_EXPOSURE;
+  renderer.setPixelRatio(1);
+
+  return {
+    scene,
+    renderer,
+    canvas: opts.canvas,
+    perspCam,
+    orthoCam,
+    activeCam: perspCam,
+    root,
+    lights: demoContent.setupLights(scene),
+    dprMax,
+    mode,
+    fov,
+    fitEnabled,
+    limits,
+    autoRotate: !!opts.autoRotate,
+  };
+}

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

@@ -0,0 +1,100 @@
+/** Modes caméra V1 (défaut : Orbit). */
+export const Sonic3dCameraMode = {
+  Orbit: "orbit",
+  Perspective: "perspective",
+  Ortho: "ortho",
+} as const;
+export type Sonic3dCameraMode =
+  (typeof Sonic3dCameraMode)[keyof typeof Sonic3dCameraMode];
+
+/** Seuil de changement form→orbit (évite de combattre autoRotate). */
+export const ORBIT_CHANGE_EPSILON = 1e-4;
+
+export const DEFAULT_OUT_INTERVAL_MS = 80;
+export const MIN_OUT_INTERVAL_MS = 16;
+/** Throttle capture canvas → `frameUrl` / `snapshot` (plus lourd que la télémétrie). */
+export const DEFAULT_SNAPSHOT_INTERVAL_MS = 250;
+export const MIN_SNAPSHOT_INTERVAL_MS = 80;
+/** MIME / qualité JPEG pour `canvas.toBlob` (frameUrl / snapshot). */
+export const SNAPSHOT_JPEG_MIME = "image/jpeg";
+export const SNAPSHOT_JPEG_QUALITY = 0.85;
+
+export const DEFAULT_FOV = 45;
+export const DEFAULT_EXPOSURE = 1;
+export const DEFAULT_MIN_DISTANCE = 0.5;
+export const DEFAULT_MAX_DISTANCE = 50;
+/** Polar Lit attrs (degrés). */
+export const DEFAULT_MIN_POLAR_DEG = 8;
+export const DEFAULT_MAX_POLAR_DEG = 172;
+/** Polar runtime avant apply des attrs (= DEFAULT_MIN_POLAR_DEG). */
+export const DEFAULT_MIN_POLAR_RAD =
+  (DEFAULT_MIN_POLAR_DEG * Math.PI) / 180;
+
+/**
+ * Champs form → viewer (auto via `dataProvider` / ancêtre `formDataProvider`).
+ */
+export const FORM_CONTROL_KEYS = [
+  "src",
+  "asset",
+  "camera",
+  "fov",
+  "exposure",
+  "autoRotate",
+  "minDistance",
+  "maxDistance",
+  "minPolar",
+  "maxPolar",
+  "distance",
+  "yaw",
+  "pitch",
+] as const;
+
+/**
+ * Entrées « pures » : ne jamais les réécrire en out si form et out partagent le DP.
+ * (`yaw` / `pitch` / `distance` restent publiables — télémétrie / two-way).
+ */
+export const FORM_INPUT_ONLY_KEYS = [
+  "src",
+  "asset",
+  "camera",
+  "fov",
+  "exposure",
+  "autoRotate",
+  "minDistance",
+  "maxDistance",
+  "minPolar",
+  "maxPolar",
+] as const;
+
+/**
+ * Clés qui comptent comme consommateurs out (gate publication paresseuse).
+ * yaw / pitch / distance exclus : un `sonic-input name="yaw"` ne doit pas
+ * activer la pub télémétrie (sinon boucle form ↔ out).
+ */
+export const OUT_CONSUMER_KEYS = [
+  "time",
+  "frame",
+  "ready",
+  "loading",
+  "hovering",
+  "pointerX",
+  "pointerY",
+  "camX",
+  "camY",
+  "camZ",
+  "targetX",
+  "targetY",
+  "targetZ",
+  "zoom",
+  "hitX",
+  "hitY",
+  "hitZ",
+  "hitObjectId",
+  /** Canvas → ObjectURL (SonicMediaRef) pour chaînage shader. */
+  "frameUrl",
+  "snapshot",
+  /** Pont live → sonic-shader (`{ element }`), publié une fois au ready. */
+  "frameSource",
+] as const;
+
+export type Sonic3dFormControlKey = (typeof FORM_CONTROL_KEYS)[number];

package/src/core/components/functional/3d/demo-content.ts

@@ -0,0 +1,45 @@
+import * as THREE from "three";
+
+/** Cube + sol de démo quand aucun asset n’est fourni. */
+function create(): THREE.Object3D {
+  const group = new THREE.Group();
+  group.name = "sonic-3d-demo";
+
+  const geo = new THREE.BoxGeometry(1, 1, 1);
+  const mat = new THREE.MeshStandardMaterial({
+    color: 0x3b82f6,
+    metalness: 0.25,
+    roughness: 0.4,
+  });
+  const box = new THREE.Mesh(geo, mat);
+  box.name = "demo-box";
+  box.position.y = 0.5;
+  group.add(box);
+
+  const ground = new THREE.Mesh(
+    new THREE.CircleGeometry(2.2, 48),
+    new THREE.MeshStandardMaterial({
+      color: 0x1a1a1a,
+      metalness: 0,
+      roughness: 0.9,
+    }),
+  );
+  ground.name = "demo-ground";
+  ground.rotation.x = -Math.PI / 2;
+  group.add(ground);
+
+  return group;
+}
+
+function setupLights(scene: THREE.Scene): THREE.Light[] {
+  const amb = new THREE.AmbientLight(0xffffff, 0.55);
+  const key = new THREE.DirectionalLight(0xffffff, 1.1);
+  key.position.set(4, 6, 3);
+  const fill = new THREE.DirectionalLight(0xb0c4ff, 0.35);
+  fill.position.set(-3, 1, -2);
+  const lights = [amb, key, fill];
+  for (const l of lights) scene.add(l);
+  return lights;
+}
+
+export const demoContent = { create, setupLights } as const;

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

@@ -0,0 +1,99 @@
+import type { Sonic3dCameraMode } from "./constants";
+import { parse } from "./parse";
+import { playback } from "./playback";
+import { reload } from "./reload";
+import { SceneRuntime } from "./scene-runtime";
+
+export type EnsureHost = {
+  releasing: boolean;
+  runtime: SceneRuntime | null;
+  dprMax: number;
+  camera: Sonic3dCameraMode;
+  fov: number;
+  exposure: number;
+  fit: boolean;
+  minDistance: number;
+  maxDistance: number;
+  minPolar: number;
+  maxPolar: number;
+  loadToken: number;
+  ready: boolean;
+  inView: boolean;
+  releaseOffscreen: boolean;
+  getBoundingClientRect: () => DOMRect;
+  clientWidth: number;
+  clientHeight: number;
+  renderRoot: ShadowRoot | null | undefined;
+  syncPlayback: () => void;
+};
+
+function getCanvas(host: EnsureHost): HTMLCanvasElement | null {
+  return (
+    (host.renderRoot?.querySelector("canvas") as HTMLCanvasElement | null) ??
+    null
+  );
+}
+
+async function ensureRuntime(host: EnsureHost) {
+  if (host.releasing || host.runtime) return;
+  const canvas = getCanvas(host);
+  if (!canvas) return;
+  try {
+    host.runtime = new SceneRuntime({
+      canvas,
+      dprMax: host.dprMax,
+      camera: parse.cameraMode(host.camera),
+      fov: host.fov,
+      exposure: host.exposure,
+      autoRotate: false,
+      fit: host.fit,
+      minDistance: host.minDistance,
+      maxDistance: host.maxDistance,
+      minPolar: reload.degToRad(host.minPolar),
+      maxPolar: reload.degToRad(host.maxPolar),
+    });
+    reload.applyOrbitLimits(host as never);
+    syncSize(host);
+    await reload.run(host as never);
+  } catch (err) {
+    reload.emitError(host as never, err);
+  }
+}
+
+function releaseRuntime(host: EnsureHost) {
+  host.loadToken++;
+  playback.stopLoop(host as never);
+  host.ready = false;
+  host.releasing = true;
+  host.runtime?.dispose(false);
+  host.runtime = null;
+  host.releasing = false;
+}
+
+function syncVisibility(host: EnsureHost) {
+  if (!host.inView && host.releaseOffscreen) {
+    releaseRuntime(host);
+    return;
+  }
+  if (host.inView && (!host.runtime || host.runtime.isLost)) {
+    void ensureRuntime(host);
+    return;
+  }
+  host.syncPlayback();
+}
+
+function syncSize(host: EnsureHost) {
+  if (!host.runtime) return;
+  const rect = host.getBoundingClientRect();
+  const cssW = Math.max(rect.width, host.clientWidth, 1);
+  const cssH = Math.max(rect.height, host.clientHeight, 1);
+  host.runtime.resize(cssW, cssH);
+  if (host.ready) host.runtime.render();
+}
+
+export const ensure = {
+  ensureRuntime,
+  releaseRuntime,
+  syncVisibility,
+  syncSize,
+} as const;