@wave3d/core 0.2.1 → 0.3.0

package/dist/shell/poster.d.ts

@@ -0,0 +1,12 @@
+//#region src/shell/poster.d.ts
+/**
+ * How the poster image maps into the container box (its CSS `object-fit`).
+ * `"fill"` (default) stretches it edge-to-edge, exactly like the canvas — which renders at the
+ * container's own aspect — so a poster captured at that aspect aligns pixel-for-pixel and the
+ * poster→canvas handoff has no visible jump. `"cover"` crops to preserve the poster's own aspect
+ * (pick it for a non-wave / different-aspect placeholder where distortion would look worse).
+ */
+type PosterFit = "cover" | "contain" | "fill";
+//#endregion
+export { PosterFit };
+//# sourceMappingURL=poster.d.ts.map

package/dist/shell/poster.js

@@ -6,10 +6,11 @@ function ensurePositioned(container) {
 }
 /**
 * Create the poster image — or adopt an existing SSR `<img data-wave3d-poster>` already inside the
-* container (no hydration flash). Positioned to cover the container and sit above the canvas.
+* container (no hydration flash). Positioned to overlay the container and sit above the canvas;
+* `fit` (default `"fill"`) sets how it maps into the box — see {@link PosterFit}.
 * Returns null when there's neither a `src` nor an adoptable image (poster is optional).
 */
-function setupPoster(container, src) {
+function setupPoster(container, src, fit = "fill") {
 	let img = container.querySelector(`img[${POSTER_ATTR}]`);
 	if (!img && !src) return null;
 	if (!img) {
@@ -26,7 +27,7 @@ function setupPoster(container, src) {
 		inset: "0",
 		width: "100%",
 		height: "100%",
-		objectFit: "cover",
+		objectFit: fit,
 		pointerEvents: "none",
 		zIndex: "1",
 		opacity: "1",

package/dist/shell/poster.js.map

@@ -1 +1 @@
-{"version":3,"file":"poster.js","names":[],"sources":["../../src/shell/poster.ts"],"sourcesContent":["// Poster management for the shell: the static image shown first (server-rendered or generated)\n// that covers the container until the live wave has painted, then crossfades out.\n\nconst POSTER_ATTR = \"data-wave3d-poster\";\n\nexport interface Poster {\n  readonly el: HTMLImageElement;\n  /** Fade the poster to transparent over `fadeMs`, then hide it so it can't block the canvas. */\n  fadeOut(fadeMs: number): void;\n  /** Re-show the poster instantly (used when a live wave is torn down back to the fallback). */\n  show(): void;\n  /** Remove the poster element from the DOM. */\n  remove(): void;\n}\n\n/** Make the container a positioning context so the absolutely-positioned poster overlays the canvas. */\nexport function ensurePositioned(container: HTMLElement): void {\n  if (getComputedStyle(container).position === \"static\") container.style.position = \"relative\";\n}\n\n/**\n * Create the poster image — or adopt an existing SSR `<img data-wave3d-poster>` already inside the\n * container (no hydration flash). Positioned to cover the container and sit above the canvas.\n * Returns null when there's neither a `src` nor an adoptable image (poster is optional).\n */\nexport function setupPoster(container: HTMLElement, src?: string): Poster | null {\n  let img = container.querySelector<HTMLImageElement>(`img[${POSTER_ATTR}]`);\n  if (!img && !src) return null;\n  if (!img) {\n    img = document.createElement(\"img\");\n    img.setAttribute(POSTER_ATTR, \"\");\n    img.decoding = \"async\";\n    img.alt = \"\";\n    img.setAttribute(\"aria-hidden\", \"true\");\n    container.appendChild(img);\n  }\n  if (src) img.src = src;\n  Object.assign(img.style, {\n    position: \"absolute\",\n    inset: \"0\",\n    width: \"100%\",\n    height: \"100%\",\n    objectFit: \"cover\",\n    pointerEvents: \"none\", // clicks/scrolls pass through to the canvas beneath\n    zIndex: \"1\", // above the WebGL canvas (which sits at the default z-order)\n    opacity: \"1\",\n    visibility: \"visible\",\n  });\n  const el = img;\n  return {\n    el,\n    fadeOut(fadeMs) {\n      if (fadeMs <= 0) {\n        el.style.opacity = \"0\";\n        el.style.visibility = \"hidden\";\n        return;\n      }\n      el.style.transition = `opacity ${fadeMs}ms ease`;\n      void el.offsetWidth; // force a style flush so the transition runs from the current opacity (1)\n      el.style.opacity = \"0\";\n      // Hide after the fade so the (transparent) poster can never intercept anything; the timer is\n      // rAF-independent so it still completes in a throttled/backgrounded tab.\n      setTimeout(() => {\n        el.style.visibility = \"hidden\";\n      }, fadeMs + 50);\n    },\n    show() {\n      el.style.transition = \"\";\n      el.style.opacity = \"1\";\n      el.style.visibility = \"visible\";\n    },\n    remove() {\n      el.remove();\n    },\n  };\n}\n"],"mappings":";AAGA,MAAM,cAAc;;AAapB,SAAgB,iBAAiB,WAA8B;CAC7D,IAAI,iBAAiB,SAAS,CAAC,CAAC,aAAa,UAAU,UAAU,MAAM,WAAW;AACpF;;;;;;AAOA,SAAgB,YAAY,WAAwB,KAA6B;CAC/E,IAAI,MAAM,UAAU,cAAgC,OAAO,YAAY,EAAE;CACzE,IAAI,CAAC,OAAO,CAAC,KAAK,OAAO;CACzB,IAAI,CAAC,KAAK;EACR,MAAM,SAAS,cAAc,KAAK;EAClC,IAAI,aAAa,aAAa,EAAE;EAChC,IAAI,WAAW;EACf,IAAI,MAAM;EACV,IAAI,aAAa,eAAe,MAAM;EACtC,UAAU,YAAY,GAAG;CAC3B;CACA,IAAI,KAAK,IAAI,MAAM;CACnB,OAAO,OAAO,IAAI,OAAO;EACvB,UAAU;EACV,OAAO;EACP,OAAO;EACP,QAAQ;EACR,WAAW;EACX,eAAe;EACf,QAAQ;EACR,SAAS;EACT,YAAY;CACd,CAAC;CACD,MAAM,KAAK;CACX,OAAO;EACL;EACA,QAAQ,QAAQ;GACd,IAAI,UAAU,GAAG;IACf,GAAG,MAAM,UAAU;IACnB,GAAG,MAAM,aAAa;IACtB;GACF;GACA,GAAG,MAAM,aAAa,WAAW,OAAO;GACxC,GAAQ;GACR,GAAG,MAAM,UAAU;GAGnB,iBAAiB;IACf,GAAG,MAAM,aAAa;GACxB,GAAG,SAAS,EAAE;EAChB;EACA,OAAO;GACL,GAAG,MAAM,aAAa;GACtB,GAAG,MAAM,UAAU;GACnB,GAAG,MAAM,aAAa;EACxB;EACA,SAAS;GACP,GAAG,OAAO;EACZ;CACF;AACF"}
+{"version":3,"file":"poster.js","names":[],"sources":["../../src/shell/poster.ts"],"sourcesContent":["// Poster management for the shell: the static image shown first (server-rendered or generated)\n// that covers the container until the live wave has painted, then crossfades out.\n\nconst POSTER_ATTR = \"data-wave3d-poster\";\n\n/**\n * How the poster image maps into the container box (its CSS `object-fit`).\n * `\"fill\"` (default) stretches it edge-to-edge, exactly like the canvas — which renders at the\n * container's own aspect — so a poster captured at that aspect aligns pixel-for-pixel and the\n * poster→canvas handoff has no visible jump. `\"cover\"` crops to preserve the poster's own aspect\n * (pick it for a non-wave / different-aspect placeholder where distortion would look worse).\n */\nexport type PosterFit = \"cover\" | \"contain\" | \"fill\";\n\nexport interface Poster {\n  readonly el: HTMLImageElement;\n  /** Fade the poster to transparent over `fadeMs`, then hide it so it can't block the canvas. */\n  fadeOut(fadeMs: number): void;\n  /** Re-show the poster instantly (used when a live wave is torn down back to the fallback). */\n  show(): void;\n  /** Remove the poster element from the DOM. */\n  remove(): void;\n}\n\n/** Make the container a positioning context so the absolutely-positioned poster overlays the canvas. */\nexport function ensurePositioned(container: HTMLElement): void {\n  if (getComputedStyle(container).position === \"static\") container.style.position = \"relative\";\n}\n\n/**\n * Create the poster image — or adopt an existing SSR `<img data-wave3d-poster>` already inside the\n * container (no hydration flash). Positioned to overlay the container and sit above the canvas;\n * `fit` (default `\"fill\"`) sets how it maps into the box — see {@link PosterFit}.\n * Returns null when there's neither a `src` nor an adoptable image (poster is optional).\n */\nexport function setupPoster(\n  container: HTMLElement,\n  src?: string,\n  fit: PosterFit = \"fill\",\n): Poster | null {\n  let img = container.querySelector<HTMLImageElement>(`img[${POSTER_ATTR}]`);\n  if (!img && !src) return null;\n  if (!img) {\n    img = document.createElement(\"img\");\n    img.setAttribute(POSTER_ATTR, \"\");\n    img.decoding = \"async\";\n    img.alt = \"\";\n    img.setAttribute(\"aria-hidden\", \"true\");\n    container.appendChild(img);\n  }\n  if (src) img.src = src;\n  Object.assign(img.style, {\n    position: \"absolute\",\n    inset: \"0\",\n    width: \"100%\",\n    height: \"100%\",\n    objectFit: fit, // \"fill\" by default so the poster maps into the box like the canvas does\n    pointerEvents: \"none\", // clicks/scrolls pass through to the canvas beneath\n    zIndex: \"1\", // above the WebGL canvas (which sits at the default z-order)\n    opacity: \"1\",\n    visibility: \"visible\",\n  });\n  const el = img;\n  return {\n    el,\n    fadeOut(fadeMs) {\n      if (fadeMs <= 0) {\n        el.style.opacity = \"0\";\n        el.style.visibility = \"hidden\";\n        return;\n      }\n      el.style.transition = `opacity ${fadeMs}ms ease`;\n      void el.offsetWidth; // force a style flush so the transition runs from the current opacity (1)\n      el.style.opacity = \"0\";\n      // Hide after the fade so the (transparent) poster can never intercept anything; the timer is\n      // rAF-independent so it still completes in a throttled/backgrounded tab.\n      setTimeout(() => {\n        el.style.visibility = \"hidden\";\n      }, fadeMs + 50);\n    },\n    show() {\n      el.style.transition = \"\";\n      el.style.opacity = \"1\";\n      el.style.visibility = \"visible\";\n    },\n    remove() {\n      el.remove();\n    },\n  };\n}\n"],"mappings":";AAGA,MAAM,cAAc;;AAsBpB,SAAgB,iBAAiB,WAA8B;CAC7D,IAAI,iBAAiB,SAAS,CAAC,CAAC,aAAa,UAAU,UAAU,MAAM,WAAW;AACpF;;;;;;;AAQA,SAAgB,YACd,WACA,KACA,MAAiB,QACF;CACf,IAAI,MAAM,UAAU,cAAgC,OAAO,YAAY,EAAE;CACzE,IAAI,CAAC,OAAO,CAAC,KAAK,OAAO;CACzB,IAAI,CAAC,KAAK;EACR,MAAM,SAAS,cAAc,KAAK;EAClC,IAAI,aAAa,aAAa,EAAE;EAChC,IAAI,WAAW;EACf,IAAI,MAAM;EACV,IAAI,aAAa,eAAe,MAAM;EACtC,UAAU,YAAY,GAAG;CAC3B;CACA,IAAI,KAAK,IAAI,MAAM;CACnB,OAAO,OAAO,IAAI,OAAO;EACvB,UAAU;EACV,OAAO;EACP,OAAO;EACP,QAAQ;EACR,WAAW;EACX,eAAe;EACf,QAAQ;EACR,SAAS;EACT,YAAY;CACd,CAAC;CACD,MAAM,KAAK;CACX,OAAO;EACL;EACA,QAAQ,QAAQ;GACd,IAAI,UAAU,GAAG;IACf,GAAG,MAAM,UAAU;IACnB,GAAG,MAAM,aAAa;IACtB;GACF;GACA,GAAG,MAAM,aAAa,WAAW,OAAO;GACxC,GAAQ;GACR,GAAG,MAAM,UAAU;GAGnB,iBAAiB;IACf,GAAG,MAAM,aAAa;GACxB,GAAG,SAAS,EAAE;EAChB;EACA,OAAO;GACL,GAAG,MAAM,aAAa;GACtB,GAAG,MAAM,UAAU;GACnB,GAAG,MAAM,aAAa;EACxB;EACA,SAAS;GACP,GAAG,OAAO;EACZ;CACF;AACF"}