staysfixed 0.1.0

package/src/freeze/mask.js

@@ -0,0 +1,187 @@
+/**
+ * Covering up the parts that are allowed to change.
+ *
+ * Some things on a screen are genuinely different every run and always will be: a live
+ * clock, a session id, a "3 minutes ago", a randomly-picked hero image. Masking them is
+ * how a picture check stays honest — the alternative is a tolerance so loose it would
+ * also hide a broken layout.
+ *
+ * Two ways to do it, and the difference matters:
+ *   paintMasks - paints over the finished photo. The layout is real, only the pixels go.
+ *   maskCss    - hides the content in the page before the photo. Use it only when the
+ *                changing content also changes the LAYOUT, because hiding content can
+ *                move everything around it, and then the mask is not the only difference.
+ */
+
+/**
+ * Turn selectors and rectangles into rectangles in device pixels.
+ *
+ * A selector that matches nothing is silently skipped: masking "the toast" on a screen
+ * with no toast is normal, not a mistake worth failing a run over.
+ *
+ * @param {import('../types.js').PageHandle} page
+ * @param {import('../types.js').Mask[]} masks
+ * @param {{deviceScaleFactor?: number, fullPage?: boolean}} [opts]
+ * @returns {Promise<import('../types.js').MaskRect[]>}
+ */
+export async function resolveMasks(page, masks, opts = {}) {
+  const dpr = opts.deviceScaleFactor && opts.deviceScaleFactor > 0 ? opts.deviceScaleFactor : 1;
+  const fullPage = opts.fullPage === true;
+
+  /** @type {string[]} */
+  const selectors = [];
+  /** @type {import('../types.js').MaskRect[]} */
+  const out = [];
+
+  for (const mask of masks ?? []) {
+    if (typeof mask === 'string') {
+      if (mask.trim()) selectors.push(mask);
+    } else if (mask && typeof mask === 'object') {
+      out.push(toDevicePixels(mask, dpr));
+    }
+  }
+
+  if (selectors.length === 0) return out;
+
+  // getBoundingClientRect is relative to the viewport, which is exactly what a viewport
+  // screenshot uses. A full-page shot is relative to the document, so the scroll offset
+  // has to go back in.
+  const source = `(() => {
+  const selectors = ${JSON.stringify(selectors)};
+  const addScroll = ${fullPage ? 'true' : 'false'};
+  const out = [];
+  for (const selector of selectors) {
+    let nodes = [];
+    try { nodes = Array.prototype.slice.call(document.querySelectorAll(selector)); }
+    catch (e) { continue; }
+    for (const el of nodes) {
+      let r = null;
+      try { r = el.getBoundingClientRect(); } catch (e) { continue; }
+      if (!r || (r.width <= 0 && r.height <= 0)) continue;
+      out.push({
+        x: r.left + (addScroll ? (window.scrollX || 0) : 0),
+        y: r.top + (addScroll ? (window.scrollY || 0) : 0),
+        width: r.width,
+        height: r.height
+      });
+    }
+  }
+  return out;
+})()`;
+
+  /** @type {any} */
+  let found = [];
+  try {
+    found = await page.evaluate(source);
+  } catch {
+    // A page that navigated mid-resolve. No masks is better than a failed run; the
+    // comparison will show the moving content, which is at least honest.
+    return out;
+  }
+
+  if (Array.isArray(found)) {
+    for (const r of found) {
+      if (!r || typeof r.x !== 'number') continue;
+      out.push(toDevicePixels(r, dpr));
+    }
+  }
+  return out;
+}
+
+/**
+ * Scale a CSS-pixel rectangle into device pixels, rounding outward so a mask never leaves
+ * a one-pixel sliver of the thing it was meant to cover.
+ *
+ * @param {import('../types.js').MaskRect} rect
+ * @param {number} dpr
+ * @returns {import('../types.js').MaskRect}
+ */
+function toDevicePixels(rect, dpr) {
+  const left = Math.max(0, Math.floor(Number(rect.x) * dpr));
+  const top = Math.max(0, Math.floor(Number(rect.y) * dpr));
+  const right = Math.max(left, Math.ceil((Number(rect.x) + Number(rect.width)) * dpr));
+  const bottom = Math.max(top, Math.ceil((Number(rect.y) + Number(rect.height)) * dpr));
+  return { x: left, y: top, width: right - left, height: bottom - top };
+}
+
+/**
+ * Paint rectangles into a decoded picture, in place.
+ *
+ * Magenta on purpose. If a mask ever drifts off the thing it was covering, a human sees a
+ * screaming pink block sitting in the wrong place instantly — which is the whole point of
+ * a tool whose job is to make changes impossible to miss.
+ *
+ * @param {import('pngjs').PNG} png
+ * @param {import('../types.js').MaskRect[]} rects
+ * @param {{color?: {r: number, g: number, b: number}}} [opts]
+ * @returns {import('pngjs').PNG} the same picture, painted
+ */
+export function paintMasks(png, rects, opts = {}) {
+  const color = opts.color ?? { r: 255, g: 0, b: 255 };
+  const width = png.width;
+  const height = png.height;
+  const data = png.data;
+
+  for (const rect of rects ?? []) {
+    const x0 = clamp(Math.round(rect.x), 0, width);
+    const y0 = clamp(Math.round(rect.y), 0, height);
+    const x1 = clamp(Math.round(rect.x + rect.width), 0, width);
+    const y1 = clamp(Math.round(rect.y + rect.height), 0, height);
+    if (x1 <= x0 || y1 <= y0) continue;
+
+    for (let y = y0; y < y1; y += 1) {
+      let i = (width * y + x0) * 4;
+      for (let x = x0; x < x1; x += 1) {
+        data[i] = color.r;
+        data[i + 1] = color.g;
+        data[i + 2] = color.b;
+        data[i + 3] = 255;
+        i += 4;
+      }
+    }
+  }
+  return png;
+}
+
+/**
+ * @param {number} n
+ * @param {number} low
+ * @param {number} high
+ * @returns {number}
+ */
+function clamp(n, low, high) {
+  if (!Number.isFinite(n)) return low;
+  return Math.min(high, Math.max(low, Math.round(n)));
+}
+
+/**
+ * CSS that flattens the named elements before the photo is taken.
+ *
+ * Painting afterwards is the better tool almost always, because the layout in the picture
+ * stays exactly what the app really did. Reach for this only when the changing content
+ * changes the size of things around it — a name that is sometimes short and sometimes
+ * long, a count that grows a column. Keeping the box and blanking what is inside it means
+ * the rest of the screen stops moving.
+ *
+ * @param {string[]} selectors
+ * @returns {Promise<string>} CSS
+ */
+export async function maskCss(selectors) {
+  const list = (selectors ?? []).filter((s) => typeof s === 'string' && s.trim());
+  if (list.length === 0) return '';
+  const joined = list.join(', ');
+  const children = list.map((s) => `${s} *`).join(', ');
+  return `${joined} {
+  background-color: #ff00ff !important;
+  background-image: none !important;
+  color: transparent !important;
+  text-shadow: none !important;
+  border-color: #ff00ff !important;
+  box-shadow: none !important;
+}
+
+${children} {
+  visibility: hidden !important;
+}
+`;
+}

package/src/freeze/motion.js

@@ -0,0 +1,206 @@
+/**
+ * Killing movement.
+ *
+ * Anything that moves is a picture that disagrees with itself. Three layers, because
+ * each one catches what the others miss:
+ *
+ *  - CSS kills declared animations and transitions, including ones that have not started.
+ *  - Page script kills what CSS cannot: running Web Animations, playing video, and
+ *    element.animate() calls the app makes at runtime.
+ *  - The protocol tells the page it is on a machine set to "reduce motion", which is the
+ *    only thing that stops well-behaved apps starting an animation in the first place.
+ *
+ * What none of this stops is an animated GIF or an autoplaying canvas draw loop that
+ * ignores requestAnimationFrame. Mask those.
+ */
+
+/**
+ * @param {{hideScrollbars?: boolean, hideCaret?: boolean}} [opts]
+ * @returns {string} CSS
+ */
+export function motionCss(opts = {}) {
+  const hideScrollbars = opts.hideScrollbars !== false;
+  const hideCaret = opts.hideCaret !== false;
+
+  const parts = [
+    // animation-duration 0 alone is not enough: a delayed animation still fires later,
+    // and an infinite one still holds a compositor layer. Say all of it.
+    `*, *::before, *::after {
+  animation: none !important;
+  animation-duration: 0s !important;
+  animation-delay: 0s !important;
+  animation-iteration-count: 1 !important;
+  animation-play-state: paused !important;
+  transition: none !important;
+  transition-duration: 0s !important;
+  transition-delay: 0s !important;
+}`,
+    // will-change promotes an element to its own compositor layer, and a promoted layer
+    // is rasterised on slightly different pixel boundaries. Take the promotion away and
+    // the same element lands on the same pixels every run.
+    `*, *::before, *::after {
+  will-change: auto !important;
+}`,
+    `html {
+  scroll-behavior: auto !important;
+}`,
+    `video, marquee {
+  animation-play-state: paused !important;
+}`,
+  ];
+
+  if (hideCaret) {
+    // A text cursor blinks. Half the runs catch it on, half catch it off.
+    parts.push(`*, *::before, *::after {
+  caret-color: transparent !important;
+}`);
+  }
+
+  if (hideScrollbars) {
+    // Scrollbars appear and disappear with content height and with the OS setting for
+    // overlay scrollbars. Hiding them costs a few pixels of width and buys a picture
+    // that does not depend on the machine that took it.
+    parts.push(`::-webkit-scrollbar {
+  display: none !important;
+  width: 0 !important;
+  height: 0 !important;
+}`);
+    parts.push(`html, body {
+  scrollbar-width: none !important;
+  -ms-overflow-style: none !important;
+}`);
+  }
+
+  return parts.join('\n\n') + '\n';
+}
+
+/**
+ * Page-side source that stops movement CSS cannot reach.
+ * @returns {string} JavaScript to evaluate in the page
+ */
+export function motionScript() {
+  return `(function () {
+  if (window.__staysfixed_motion) return;
+  window.__staysfixed_motion = true;
+
+  // A finished-looking stub. Libraries await animation.finished before showing the next
+  // thing; if we simply removed animate() those apps would hang half-rendered forever.
+  function stubAnimation() {
+    var done = Promise.resolve();
+    return {
+      id: '',
+      effect: null,
+      playState: 'finished',
+      playbackRate: 1,
+      currentTime: 0,
+      startTime: 0,
+      finished: done,
+      ready: done,
+      onfinish: null,
+      oncancel: null,
+      play: function () {},
+      pause: function () {},
+      cancel: function () {},
+      finish: function () {},
+      reverse: function () {},
+      persist: function () {},
+      commitStyles: function () {},
+      updatePlaybackRate: function () {},
+      addEventListener: function () {},
+      removeEventListener: function () {},
+      dispatchEvent: function () { return true; }
+    };
+  }
+
+  try {
+    if (window.Element && Element.prototype && Element.prototype.animate) {
+      Element.prototype.animate = function () { return stubAnimation(); };
+    }
+  } catch (e) {}
+
+  function quiet(root) {
+    try {
+      var vids = root && root.querySelectorAll ? root.querySelectorAll('video') : [];
+      for (var i = 0; i < vids.length; i++) {
+        try {
+          vids[i].autoplay = false;
+          vids[i].pause();
+          // Seek to the first frame so the poster-or-frame-0 question has one answer.
+          if (vids[i].currentTime !== 0) vids[i].currentTime = 0;
+        } catch (e) {}
+      }
+    } catch (e) {}
+    try {
+      if (typeof document.getAnimations === 'function') {
+        var anims = document.getAnimations();
+        for (var j = 0; j < anims.length; j++) {
+          var a = anims[j];
+          var forever = false;
+          try {
+            var t = a.effect && a.effect.getTiming ? a.effect.getTiming() : null;
+            forever = Boolean(t && t.iterations === Infinity);
+          } catch (e) {}
+          if (forever) {
+            // A spinner has no end state, so hold it at its first frame. Every run then
+            // photographs the same frame instead of whichever one the shutter caught.
+            try { a.pause(); a.currentTime = 0; } catch (e) { try { a.cancel(); } catch (e2) {} }
+          } else {
+            // finish(), NOT cancel(). This one cost a wrong picture of a real app.
+            //
+            // cancel() throws the animation away and puts the element back where it
+            // STARTED. So a sidebar that collapses with a 200ms slide was photographed
+            // still open — the click worked, the content moved, and the panel snapped
+            // back to its opening position the instant we cancelled. finish() jumps to
+            // the end state, which is what a person would see a moment later, and that
+            // is the picture worth keeping.
+            try { a.finish(); } catch (e) { try { a.cancel(); } catch (e2) {} }
+          }
+        }
+      }
+    } catch (e) {}
+  }
+
+  function sweep() { quiet(document); }
+  sweep();
+  try { document.addEventListener('DOMContentLoaded', sweep); } catch (e) {}
+  try { window.addEventListener('load', sweep); } catch (e) {}
+
+  // Anything rendered after load brings its own animations with it — a spinner mounted by
+  // a router, a toast, a lazy image fading in. Re-sweep whenever the page changes, but on
+  // the next microtask so we are not mutating inside the mutation we are being told about.
+  try {
+    var queued = false;
+    var observer = new MutationObserver(function () {
+      if (queued) return;
+      queued = true;
+      Promise.resolve().then(function () { queued = false; sweep(); });
+    });
+    observer.observe(document, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['class', 'style']
+    });
+    window.__staysfixed_motionObserver = observer;
+  } catch (e) {}
+})();`;
+}
+
+/**
+ * Tell the page it is running on a machine set to reduce motion, and optionally pin the
+ * colour scheme so a picture does not flip to dark because the CI box prefers dark.
+ *
+ * @param {import('../types.js').PageHandle} page
+ * @param {{colorScheme?: 'light'|'dark'}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function reduceMotionCdp(page, opts = {}) {
+  /** @type {{name: string, value: string}[]} */
+  const features = [{ name: 'prefers-reduced-motion', value: 'reduce' }];
+  if (opts.colorScheme) features.push({ name: 'prefers-color-scheme', value: opts.colorScheme });
+  try {
+    await page.send('Emulation.setEmulatedMedia', { features });
+  } catch {
+    // Not every target carries Emulation.setEmulatedMedia. The CSS layer still applies.
+  }
+}