docs: Set fixed dimensions on absolute images

[cpAdm]

By having a fixed width and height for images, room is reserved for the images, and thus preventing layout shifts.

Code snippet used to update the images (AI prompted)

import { promises as fs } from 'node:fs';
import path from 'node:path';
import process from 'node:process';
import { imageSize } from 'image-size';

const ROOT_DIR = path.resolve('./docs/src');

// Plain Markdown image syntax (no title support intentionally)
const IMAGE_REGEX = /!\[([^\]]*)]\((https?:\/\/[^\s)]+)\)/g;

async function main() {
  console.log(`Scanning: ${ROOT_DIR}`);
  await walk(ROOT_DIR);
  console.log('Done.');
}

async function walk(dir: string): Promise<void> {
  const entries = await fs.readdir(dir, { withFileTypes: true });

  for (const entry of entries) {
    const fullPath = path.join(dir, entry.name);

    if (entry.isDirectory())
      await walk(fullPath);
    else if (entry.isFile() && fullPath.endsWith('.md'))
      await processMarkdown(fullPath);
  }
}

async function processMarkdown(filePath: string) {
  let content = await fs.readFile(filePath, 'utf8');
  let modified = false;

  const matches = [...content.matchAll(IMAGE_REGEX)];

  for (const match of matches) {
    const [original, alt, url] = match;

    try {
      const dimensions = await getImageDimensions(url);

      if (!dimensions?.width || !dimensions?.height) {
        console.warn(`⚠ Could not determine size: ${url}`);
        continue;
      }

      const replacement = `<img src="${url}" alt="${escapeHtml(alt)}" width="${dimensions.width}" height="${dimensions.height}" />`;

      content = content.replace(original, replacement);
      modified = true;

      console.log(
          `✔ ${path.relative(ROOT_DIR, filePath)} → ${url} (${dimensions.width}x${dimensions.height})`
      );
    } catch (err) {
      console.warn(`✖ Failed: ${url}`);
    }
  }

  if (modified)
    await fs.writeFile(filePath, content, 'utf8');

}

async function getImageDimensions(url: string) {
  const response = await fetch(url);

  if (!response.ok)
    throw new Error(`HTTP ${response.status}`);


  const buffer = Buffer.from(await response.arrayBuffer());
  return imageSize(buffer);
}

function escapeHtml(str: string): string {
  return str
      .replace(/&/g, '&amp;')
      .replace(/"/g, '&quot;')
      .replace(/</g, '&lt;')
      .replace(/>/g, '&gt;');
}

main().catch(err => {
  console.error(err);
  process.exit(1);
});

Also needs: microsoft/playwright.dev#1973

Closes: microsoft/playwright.dev#1899

[Skn0tt]

neat! i like the solution.

[yury-s]

Should we also land a script that would check/update that the dimensions of the images match the ones in the tags?