From ee948930fe44e805094deaa9f21e0d97f2a741b1 Mon Sep 17 00:00:00 2001
From: "Tommy D. Rossi" <beats.by.morse@gmail.com>
Date: Sat, 21 Feb 2026 15:58:21 +0100
Subject: [PATCH] website: move placeholders to src/assets for Vite base64
 inlining, add LazyVideo component
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Placeholders are now generated into src/assets/placeholders/ instead of
public/ so Vite's asset pipeline processes them. Since all are < 4KB,
Vite auto-inlines them as base64 data URIs via assetsInlineLimit — zero
extra HTTP requests for placeholders.

- Static imports resolve to data:image/png;base64,... at build time
- JSDoc on placeholder props documents why static imports are required
  (synchronous availability, Vite inlining) and warns against dynamic
  imports and public/ paths
- New LazyVideo component: same pixelated poster pattern, uses native
  <video preload="none" loading="lazy"> for zero-JS lazy loading
---
 website/scripts/generate-placeholders.ts      |  16 +-
 .../placeholders/placeholder-favicon-16.png   | Bin 0 -> 1163 bytes
 .../placeholders/placeholder-favicon-32.png   | Bin 0 -> 636 bytes
 .../placeholders/placeholder-og-image.png     | Bin 0 -> 1158 bytes
 .../placeholder-screenshot@2x.png             | Bin 0 -> 1246 bytes
 website/src/components/markdown.tsx           | 141 ++++++++++++++++++
 website/src/routes/_index.tsx                 |   3 +-
 7 files changed, 155 insertions(+), 5 deletions(-)
 create mode 100644 website/src/assets/placeholders/placeholder-favicon-16.png
 create mode 100644 website/src/assets/placeholders/placeholder-favicon-32.png
 create mode 100644 website/src/assets/placeholders/placeholder-og-image.png
 create mode 100644 website/src/assets/placeholders/placeholder-screenshot@2x.png

diff --git a/website/scripts/generate-placeholders.ts b/website/scripts/generate-placeholders.ts
index 61304c1..3c17893 100644
--- a/website/scripts/generate-placeholders.ts
+++ b/website/scripts/generate-placeholders.ts
@@ -2,9 +2,14 @@
  * Generate pixelated placeholder images for the website.
  *
  * Scans website/public/ for all image files (png, jpg, jpeg, webp) and
- * generates a tiny 32px-wide version of each. When displayed at full size
- * with CSS `image-rendering: pixelated` (nearest-neighbor / point sampling),
- * these produce a crisp mosaic effect instead of a blurry upscale.
+ * generates a tiny 32px-wide version into src/assets/placeholders/.
+ * When displayed at full size with CSS `image-rendering: pixelated`
+ * (nearest-neighbor / point sampling), these produce a crisp mosaic effect.
+ *
+ * Output goes to src/assets/placeholders/ (NOT public/) so that Vite's
+ * asset pipeline processes them. Since all placeholders are < 4KB, Vite
+ * automatically inlines them as base64 data URIs via assetsInlineLimit,
+ * eliminating extra HTTP requests.
  *
  * Skips files that already have the `placeholder-` prefix.
  * Skips regeneration if the placeholder is newer than the source image.
@@ -17,11 +22,14 @@ import path from "node:path";
 import fs from "node:fs";
 
 const PUBLIC_DIR = path.resolve(import.meta.dirname, "../public");
+const OUTPUT_DIR = path.resolve(import.meta.dirname, "../src/assets/placeholders");
 const PLACEHOLDER_PREFIX = "placeholder-";
 const PLACEHOLDER_WIDTH = 32;
 const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp"]);
 
 async function main() {
+  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+
   const entries = fs.readdirSync(PUBLIC_DIR);
 
   const images = entries.filter((name) => {
@@ -41,7 +49,7 @@ async function main() {
     const inputPath = path.join(PUBLIC_DIR, name);
     const ext = path.extname(name);
     const base = path.basename(name, ext);
-    const outputPath = path.join(PUBLIC_DIR, `${PLACEHOLDER_PREFIX}${base}${ext}`);
+    const outputPath = path.join(OUTPUT_DIR, `${PLACEHOLDER_PREFIX}${base}${ext}`);
 
     // Skip if placeholder already exists and is newer than source
     if (fs.existsSync(outputPath)) {
diff --git a/website/src/assets/placeholders/placeholder-favicon-16.png b/website/src/assets/placeholders/placeholder-favicon-16.png
new file mode 100644
index 0000000000000000000000000000000000000000..0d386bd5b8f978b4aa5394d940aaae2193780458
GIT binary patch
literal 1163
zcmV;61a$j}P)<h;3K|Lk000e1NJLTq001BW001Be1^@s6b9#F800009a7bBm000XU
z000XU0RWnu7ytkSJxN4CRCwCOmrF}qK@`XDH|VaPqw9Wyev~d<xpbk%w}^_0;sdG}
zQBk_^g$OE5X;C)@s-Q_1T1A_*z7i`*PS0<c3AfjK6Wg?O;AF_XbI<vo|9Q-e=h;zT
zU;nJBsp&;)YwPP+EcQm_eM?JAO6QEuw<-@R1$|%CxumlM#XjeK!LH}KuPVo?=N)>{
zj~(oJ{?X9T@Vv3H@ue=VQ;Dm5RQaruRk`~^0DPBG!)cWdR&O14uxAYG2haGUs9xzy
zT^D<+b5iAtzWc6o9%Vkmp~ihu@&N%vPURc=&};R_uxCI(hxI(B@(I)^YHMqgDu#Yb
zoIcA6c4FA|nwy(nLyNuy*<D9Rham0k?dGFefjAxLbGogQ*sJqM3>%vyAF$wWdL9&~
z--bEv=}*EY$QO_X0qAp4mPAAKi||ap`y&9@!5(%!TOw%^B`o%iJ|{fGFao$5a^V|x
zJzJ;LdM@ZWiw6b<WNK<k=I7^SVPQe0r>A9PWJG#<dtE#YBbrcUW}X7fR!7FO&En3M
zT6qDA@EGIU+uM>%Cgt$(P<D29WOa2_W@ct&cz9TPdU^~{$I4Tgaeab5@WcKo`WN60
z0Pq~+=jZ2gb#*0|mzR=Gr)7VCUlNIg0W&u@CleDBhOMryt}=s8A^?~^;n}WL2zECI
z0NU{!<NopR@F3UM*K%@lVgPP!ZOP)|q5;y^*C(Bwon;_VT@$-7P_!aJ0L;W3+VMO%
zN~MzI^Lfc;vjzx2cXxMXV`D?&@wfrv5;p=!(X&WOVE~9H2?x#4UTqYMMFZ&U?94DS
zIy!1Xg7L7D#jY2XB(BcMb`p-5L;F)ez!m@iPbi`QAdvuEHdAV3I|)b3p}o?$xw(<!
z<6~J~UY7p;e%Ev&bHS@nCgqt@BMhgfr-tIF0Yj-&O4ircO)>($TDSD7)hoGx7nB;=
zPQpcvTrMYjdwViDIcY#+oKV&TfDVTuJlfpcG}#_C3Wb7UU~O$p#>U1B@M@hgvI>IL
zK$D>-92^{&MDx>*=NM;@Cr3v|va+&bzM%}Ga==wVXdehxLw9$#jE|3-o<JU8kc7iy
zXlKUw{r$apPER0jV9r%SR38ZKg#Ki7AJbT9GSoSxMz)i1#2ni39OI1J+gtO0X=%xn
za!{AQ6Nc^uVL<SN4o8i%K~ZXWNWu|wXvcGm6PipWW7ZB14n8VJ|6UNf8%C8SEYRU-
zGSs;%HMey`JDy|w;^M*p9U2;Xlnegd@T)y~=c@s5jfwUO8*UpWPu%uRo<KW>k=fbV
z@|GQS9!PQi=Lr7P({R{U>;40bm_s|BW8BYR*oi2?B}5;Fo(aQ@haEhEpxhBI82d+O
z!hdlpu5=iAbSnNA_ktjRiuZ#5elx0cH?()UT#a|byuD+F-wmT~$0UfoFJx-G9cS$=
d`(xPc_$Nbw(REquQ$hd$002ovPDHLkV1i3UA}jy^

literal 0
HcmV?d00001

diff --git a/website/src/assets/placeholders/placeholder-favicon-32.png b/website/src/assets/placeholders/placeholder-favicon-32.png
new file mode 100644
index 0000000000000000000000000000000000000000..425b1ad52df32547a3e60ccf1012ed8c3c5b1787
GIT binary patch
literal 636
zcmV-?0)zdDP)<h;3K|Lk000e1NJLTq001BW001Be1^@s6b9#F800009a7bBm000XU
z000XU0RWnu7ytkQE=fc|RCwCWS4*nGFcb}L;;q89xr){g2;x8#2M$D06zklfsL+Yx
z0u-D$(kcoa)Oufzq~a@Wno70r!a>lOb8>&lWrae4y&%Jp<;Zb#IZTcnhs9xYI2<kq
zg}@bSZ1JC+*rOx%%nFVt=PUUSht9DTn^3}V#NL|V`Xc~e7#|=F!^jiixn27rxd(VV
z!$e%RDF^^(mWkwWQV;;n92412DWS_mnS?IN=krhKy8ie~P=Luqt%j1<>vfvVW;CDA
z$uJD6)oN5M7LyXQW1?Y%3IMrhx7&>lhXbuvD;f@mRIOH@o_SM%#YEQ%6|h(=D99Yg
zq5XdU5ZG?Fsa!5ULlr}S&14mTlfmscxy)?arp;zUlgWgd%_fyfB~>8~ll69Nf|$eY
zs&+n~X}MfdqtQ?i;j$=|NI1kiu1%*?B`-t@Kp2p4h`FkrPNzp+Bq9KtAls2}sv#H*
z2Fl6ER2KQmG0d*lYb^3u0^m|)yUZ?^3-$Z`<OKkzbCg<?S(Zh;UN2S%T$P1LM$~zb
z+i~(YMYv4$D#m7LGDtFi!olqzeM5vJZN))70Zqm$H80@+koiR%k4I{?S~3x~^fC(a
z0y-R;jK9u<MBMLp8jr`a%gT~o$5HQtpx+<@CkOd@y{1Z~5_uh)NxpI*0&d62K^~C<
z=0~1nF<wudfAJ_y{aKz7L&CQOXx?Drjb@{?MzdED+82gXJ!m)$8qYfkj_2L5@%$H+
WE8yS9KVM@20000<MNUMnLSTZqau-Jc

literal 0
HcmV?d00001

diff --git a/website/src/assets/placeholders/placeholder-og-image.png b/website/src/assets/placeholders/placeholder-og-image.png
new file mode 100644
index 0000000000000000000000000000000000000000..5cfdbeaf775978022155e471c4684c84f4995b6b
GIT binary patch
literal 1158
zcmV;11bO?3P)<h;3K|Lk000e1NJLTq001BW000pP1^@s6yj-sQ00009a7bBm000XU
z000XU0RWnu7ytkSI7vi7RCwC8mVZo?bsWbJ`>U-ExZ{q4JBmjBD9!S+fglFnX_j}-
z{Xn27NSaC6s2JEx>kkOVm^5clGncVdCMz?rjhGq|iNO63vuO~9iYYSJawgpKe4ovC
z@1vX951VV<ZSQ@bAK&Nuc|Gs%=lOh26Uuf#e#8km-vLoZRXd>UlAv^ZAo@K}gLx3&
zJq0mT4)J3R#F=dn=XOJ!-w!c<2+9Q?6{L>*Cuy!^I5C;)L`Wh;i4&rd+CsIvp&TNB
zk03`2Ax@M+{oy63qcu>+nxOvlAtBlbaRA~%FBco20uh*-2hv<xDB*IpgvsR+LitW8
z>lnO-V~Yf_pAdZnII@Z^6hREHfjC(S_4FH1&%Q;7_o1HO&4u<sO!PsS;Gz@9c>XOl
zcyj<hKj6ZpbP2!axG?3EAg`wV8>nWg%>~iphVT>OSOL`UOCUy`hd8x?F4RLk_cq^t
z7nJcYpp1PEae61j*hh3`FBk8MIMW~5rm*}34N`x=X~yq!;i6T-FN^4e-H9u!oS1r!
zTT;i7xggU8`7kw@2l@DukVn=)K2-(zY%S!`M#x8N5$Y*N=wRWsdCJK$LNqYI$8@BV
zAU!+|JJcV6xZZ)eUR<8<g=}?0&2r=F3O7*X0xGC?c--j)0(rpk0$`*V7+nhtRRFy&
z18t>1EAQ`da-IkHn#cZpTpglQW1ARoJJrsB-5mQOdGhD{(0rM;9Q*FJqkFa;-^{b2
z*SZt~OKkA1TngXQx$tkY!M}AG0^3(mD-mdt5U6n=P_+!fs$2wL<J@W+`s;EK*kZ>(
zvmGO!N>GQ_Gr$hW6CDhGeUknq2lUA%nD0u3F3E({*|U&svtjOn1z4DwiHyZdke->1
zhtjh!Z@v}Q2Qx5p*1d>}H$Z1JL7$ietu6s+Gw;Eo#Sg=rl8Siaop>~B4&<&9D5K2`
ze(-nuY5hMYVXRgQU0giEV}f3fJ1iEM5{)n?CnLpThQ*u=GnHgYoW5o-BtWaZ9dWU-
z(+WRlG#EJ70)t+MTW`}M_x@B&?es!)y#V=4JCuuqH~1=o(C~-<OEY3(rpJslBjjf0
zREr04=ZjE=TUoq%SThb^OGYs<K>7a;5W_|OO*aZ2zIV%v2tX<UYMBRbx}a?1SMf<H
zl&)7H2I^SU8dy`P6ZQP08>8ev3IWy=;C0rLde)F8R?-&cL@Pn|ltSz+hUh4S@|8DA
z0Ley#%2-j$Sy5kMMXhE&Y$inW6A<q{PM89SR`!?<Pm};mMobkEpoEQWEyoH%Y@`!4
z4B9}Lt*o#gaC=zfq61(sV$#94ceB$Lvcs+>#5zJ$GVn%jOC!%eW1s1X7J%M3-C-3w
z0Uo0Zc??)gJ<DrV)O&<DKu7wbv<2z$MugkEl0|?V0`UKa;$^#khUc5<L`V4T3E=bK
YH_U_W6p@7YsQ>@~07*qoM6N<$f&h~gy#N3J

literal 0
HcmV?d00001

diff --git a/website/src/assets/placeholders/placeholder-screenshot@2x.png b/website/src/assets/placeholders/placeholder-screenshot@2x.png
new file mode 100644
index 0000000000000000000000000000000000000000..c4e1c3f3b0a72cac8087d5bb62e4252596afd66f
GIT binary patch
literal 1246
zcmV<41R?v0P)<h;3K|Lk000e1NJLTq001BW000yS1^@s6?2$iD00009a7bBm000XU
z000XU0RWnu7ytkSkV!;ARCwC8mVHc>Wf;Z}=YTf*8i6n)3#>8u5U}9DIDA+mS8%=&
z`HBQOu@t4jSxif8>6}ZQX^n<XbQRi6qPbL-LSPB<r7)~C(_xByXv@vi!}Gkr)pZVM
zxu*S5dH%R|zt4Hkd+y(RJ@<3pM<vn?5R3JYOR23!$io)MHY;SO8RI>fkbU`(XY5c0
zc0gSD24ds{b&@)DU!)QX^bmRjWG=Og5L*}<&5-RDC|%U4EXdP^P|j5n;zP*6FCd4S
zAYCBc{~Jc-NHoBaX26)0$%~o1l5sm@6P-9g0H+K6d5}N74(0qxC>J+Fxx5R?Py>`<
zCrBIB^`Ajhe`pQ3nQFxCbR$F_6PHmN2(gdrV}x+J(3=J2hXT5=6v~Bnp!~WK%3uv4
zK8GAWNVO26-R;P~1i1dJ5jPTzxS3{z!%8P?tcf+$4re`ZE7}OrV})`$2g=zZx==<J
zs-RrjM2PKlVISnxBUHP4TRN#8mm|{U%1QUS=iUI<qD=Tbju0tE+<KW#<nqnSsSgNI
zZ-V@m5S@hRTf|~4fIMFUIZz3Cc|G5}nsGP8&(#q9YgsE5kmu}>mp1U;rvx}mwYuDq
zBONX{Nf0^Odk0`B(u8X<CS2DNVgVrxbfS<>tfoF8$Po(!YeDp}7S8ZQT(Ch5*dcyd
z1JSV(;?Qdl2dof{84xX0w;AFrK?heujMh?LGhr(u-5Kq;YnxQVVVU?X+>9GhX55N1
z!I7kgV$fr}I0F;!=`pd#h>0dMCOa}Q*^>iw76C^~fVu*p#thW*{vHFy>y1F86_c&}
zULOGlRx!a&H^6u9<Xv}fLGJ8Gyc!aXf~Ue^3!M+UHU%r5i$}RG5fy1VR2Zl%9p21N
zKzU9wN)1{R>B3Q*NF_(0Ff|ON`dHYrlTeZog(d0p@P26mkMA<bD^3TFx(oE)Cq?ye
z;7s_<4#JF?eh8csjJVVk1c!$qJT?~5@d=n08;^*XILrx+z}(3B2nv1%4?N<F8NPma
z(AOW+A9@r|goGk8MhpKy{*LeC&_zED$5*VG{&fUsow9xSABxaN;|(9R2Gg8Tqk%@P
z=Cuaij2g9<D|&0x@bT9C6{q=l|4q)%oX<_?wMwOeZtg6IS{~o}T!`LnQ{D4wA7Og$
zXk@AoRn7<Qm(*TfuBZ(OfY@w;@-YjtE)Sx$3i8L@Ea3f+7aMp=sKEp5sE0fR@FW4M
zj8N9Imu%(f*_i`bZ)0Cs4%u7=d5raOoX5G#<{^L}0<0jwTkNXuvX5+JJyhpI>?(lx
z>=ky|T*wB_m`00-0A>YXjJ-sbaL_qh`zk`LqZ6AJLvC9HrG}lg&g?;efB-l$X@52W
zmT<1T!RvB%)wkJE*D~=IuJ>}?Z1xa<KLHl9i>B)_X4X%QdK;52rz&~<5#vFE9QTw1
zj|Jd%5@$&&9e9y4GHJHK<;EC`Q|xE*7OKPQApl<j#4%w!XG1a_c!6_;5Dq(&?`7g<
zi)+d%-JWv5j{qqIcwP_3OH@9SuQx$_Ih9;|Z*fgn=bxQF0hh|$_#v{DCjbBd07*qo
IM6N<$g0@vQ5dZ)H

literal 0
HcmV?d00001

diff --git a/website/src/components/markdown.tsx b/website/src/components/markdown.tsx
index 02f4aee..a234484 100644
--- a/website/src/components/markdown.tsx
+++ b/website/src/components/markdown.tsx
@@ -434,6 +434,20 @@ export function PixelatedImage({
   style,
 }: {
   src: string;
+  /**
+   * URL of the tiny pixelated placeholder image. Use a static import so Vite
+   * inlines it as a base64 data URI (all placeholders are < 4KB, well under
+   * Vite's default assetsInlineLimit of 4096 bytes). This makes the
+   * placeholder available synchronously on first render with zero HTTP
+   * requests. Do NOT use dynamic imports or public/ paths — dynamic imports
+   * add a microtask delay, and public/ files bypass Vite's asset pipeline.
+   *
+   * @example
+   * ```tsx
+   * import placeholderScreenshot from "../assets/placeholders/placeholder-screenshot@2x.png";
+   * <PixelatedImage placeholder={placeholderScreenshot} src="/screenshot@2x.png" ... />
+   * ```
+   */
   placeholder: string;
   alt: string;
   width: number;
@@ -504,6 +518,133 @@ export function PixelatedImage({
   );
 }
 
+/* =========================================================================
+   Lazy video with pixelated poster placeholder
+   Same visual pattern as PixelatedImage but for <video> elements.
+   Poster layers (pixelated → real) show through the transparent video element.
+   Video uses native loading="lazy" + preload="none" so zero bytes are
+   downloaded until the element is near the viewport and the user clicks play.
+   No custom IntersectionObserver needed — all native HTML attributes.
+   ========================================================================= */
+
+export function LazyVideo({
+  src,
+  poster,
+  placeholderPoster,
+  width,
+  height,
+  type = "video/mp4",
+  className = "",
+  style,
+}: {
+  src: string;
+  poster: string;
+  /**
+   * URL of the tiny pixelated poster placeholder. Use a static import so Vite
+   * inlines it as a base64 data URI (all placeholders are < 4KB, well under
+   * Vite's default assetsInlineLimit of 4096 bytes). This makes the
+   * placeholder available synchronously on first render with zero HTTP
+   * requests. Do NOT use dynamic imports or public/ paths — dynamic imports
+   * add a microtask delay, and public/ files bypass Vite's asset pipeline.
+   *
+   * @example
+   * ```tsx
+   * import placeholderPoster from "../assets/placeholders/placeholder-demo-poster.png";
+   * <LazyVideo placeholderPoster={placeholderPoster} poster="/demo-poster.png" ... />
+   * ```
+   */
+  placeholderPoster: string;
+  width: number;
+  height: number;
+  type?: string;
+  className?: string;
+  style?: React.CSSProperties;
+}) {
+  const [posterLoaded, setPosterLoaded] = useState(false);
+
+  // Handles cached poster images (same pattern as PixelatedImage)
+  const posterRef = useCallback((img: HTMLImageElement | null) => {
+    if (img?.complete && img.naturalWidth > 0) {
+      setPosterLoaded(true);
+    }
+  }, []);
+
+  return (
+    <div
+      className={className}
+      style={{
+        position: "relative",
+        width: "100%",
+        maxWidth: `${width}px`,
+        aspectRatio: `${width} / ${height}`,
+        overflow: "hidden",
+        ...style,
+      }}
+    >
+      {/* Pixelated poster placeholder: loads instantly (~500 bytes) */}
+      <img
+        src={placeholderPoster}
+        alt=""
+        aria-hidden
+        width={width}
+        height={height}
+        style={{
+          position: "absolute",
+          inset: 0,
+          width: "100%",
+          height: "100%",
+          objectFit: "cover",
+          imageRendering: "pixelated",
+          zIndex: 0,
+        }}
+      />
+      {/* Real poster: fades in over the pixelated placeholder */}
+      <img
+        ref={posterRef}
+        src={poster}
+        alt=""
+        aria-hidden
+        width={width}
+        height={height}
+        onLoad={() => {
+          setPosterLoaded(true);
+        }}
+        style={{
+          position: "absolute",
+          inset: 0,
+          width: "100%",
+          height: "100%",
+          objectFit: "cover",
+          opacity: posterLoaded ? 1 : 0,
+          transition: "opacity 0.4s ease",
+          zIndex: 1,
+        }}
+      />
+      {/* Video: transparent until playing, native lazy + no preload.
+          Controls float on top of poster layers. No poster attr needed
+          because the img layers handle the visual placeholder.
+          loading="lazy" is a newer HTML attr not yet in React's TS types. */}
+      <video
+        controls
+        preload="none"
+        {...{ loading: "lazy" } as React.VideoHTMLAttributes<HTMLVideoElement>}
+        width={width}
+        height={height}
+        style={{
+          position: "relative",
+          width: "100%",
+          height: "100%",
+          objectFit: "cover",
+          zIndex: 2,
+          background: "transparent",
+        }}
+      >
+        <source src={src} type={type} />
+      </video>
+    </div>
+  );
+}
+
 /* =========================================================================
    Chart placeholder (dark box with animated line)
    ========================================================================= */
diff --git a/website/src/routes/_index.tsx b/website/src/routes/_index.tsx
index 8742067..c8764ff 100644
--- a/website/src/routes/_index.tsx
+++ b/website/src/routes/_index.tsx
@@ -20,6 +20,7 @@ import {
   Li,
   PixelatedImage,
 } from "website/src/components/markdown";
+import placeholderScreenshot from "../assets/placeholders/placeholder-screenshot@2x.png";
 
 export const meta: MetaFunction = () => {
   const title = "Playwriter - Control your Chrome with Playwright API";
@@ -73,7 +74,7 @@ export default function IndexPage() {
       <div className="bleed" style={{ display: "flex", justifyContent: "center" }}>
         <PixelatedImage
           src="/screenshot@2x.png"
-          placeholder="/placeholder-screenshot@2x.png"
+          placeholder={placeholderScreenshot}
           alt="Playwriter controlling Chrome with accessibility labels overlay"
           width={1280}
           height={800}