image-deep-research 0.0.0-stage → 1.2.0

package/skills/image-deep-research/scripts/images.mjs

@@ -0,0 +1,393 @@
+#!/usr/bin/env node
+/* image-deep-research/images - search open image collections, check every
+   result is really an image, and keep the licence beside it.
+
+   node images.mjs "<query>" [--sources openverse,commons,aic,met] [--n 6]
+     --commercial      keep only licences that allow commercial use and changes
+                       (drops NC and ND; CC0, public domain, BY and BY-SA stay)
+     --out <dir>       where results.json, the moodboard and downloads go
+     --sheet           tile the verified images into a moodboard contact sheet
+                       (needs Chrome, Edge or Chromium)
+     --download        save each verified image into <out>/images
+     --json            print the results as JSON instead of a table
+     --compact         one line per verified result, no URLs, and one compact
+                       sheet of up to 16 numbered tiles (1288x812, 1,334 image
+                       tokens); implies --sheet, and --n defaults to 4
+
+   node images.mjs --pick 3,7 --results <out>/results.json
+                       the full record (licence URL, image URL, page) of the
+                       results numbered 3 and 7 in that run; no network
+
+   No keys. Openverse (about 800M CC and public-domain images), Wikimedia
+   Commons, the Art Institute of Chicago (public-domain works only) and the
+   Metropolitan Museum of Art (Open Access works only). Every URL is fetched
+   before it is reported: a result whose URL does not answer with an image is
+   listed as unverified and never put on the moodboard. */
+
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { parseArgs, int } from './args.mjs';
+import { checkUrl, publicFetch, readLimited } from './network.mjs';
+
+/* The Art Institute of Chicago's image server answers 403 to any user agent
+   that carries a URL (measured 2026-09-25: "image-deep-research/1.0" gets the
+   image, the same string plus "(https://github.com/...)" gets 403), while
+   Wikimedia asks for contact details in it. So the contact goes to Wikimedia
+   only, and to the AIC in the header its API documents for that purpose. */
+export const UA = 'image-deep-research/1.0';
+export const UA_CONTACT = 'image-deep-research/1.0 (https://github.com/ridelink0/image-deep-research)';
+export const SOURCES = ['openverse', 'commons', 'aic', 'met'];
+
+// Commons wraps QuickStatements hints in hidden spans (title QS:P1476,...); they are not the title.
+const strip = (html) => String(html || '').replace(/<(span|div)[^>]*display:\s*none[^>]*>[\s\S]*?<\/\1>/gi, '').replace(/<[^>]*>/g, '').replace(/&amp;/g, '&').replace(/&quot;/g, '"').replace(/&#0?39;/g, "'").replace(/\s+/g, ' ').trim();
+
+/* True when a licence allows commercial use and modification. */
+export function commercialOk(licence) {
+  const l = String(licence || '').toLowerCase();
+  if (!l) return false;
+  if (/\b(nc|nd)\b|noncommercial|non-commercial|noderiv|no-deriv/.test(l)) return false;
+  return /^(?:cc0(?:\s+\((?:public domain|met open access)\))?|public domain|pdm|pd|(?:cc[ -])?by(?:-sa)?(?:\s+\d(?:\.\d)?)?)$/.test(l);
+}
+
+export function parseOpenverse(json) {
+  return (json.results || []).map((r) => ({
+    source: 'openverse',
+    title: r.title || '',
+    creator: r.creator || '',
+    licence: r.license ? (['cc0', 'pdm'].includes(r.license) ? r.license.toUpperCase() : `CC ${r.license.toUpperCase()} ${r.license_version || ''}`.trim()) : '',
+    licenceUrl: r.license_url || '',
+    url: r.url,
+    page: r.foreign_landing_url || '',
+    width: r.width || null,
+    height: r.height || null,
+    via: r.provider || r.source || '',
+  })).filter((r) => r.url);
+}
+
+export function parseCommons(json) {
+  const pages = Object.values((json.query && json.query.pages) || {}).sort((a, b) => (a.index || 0) - (b.index || 0));
+  return pages.map((p) => {
+    const ii = (p.imageinfo || [])[0] || {};
+    const md = ii.extmetadata || {};
+    return {
+      source: 'commons',
+      title: strip(md.ObjectName && md.ObjectName.value) || String(p.title || '').replace(/^File:/, ''),
+      creator: strip(md.Artist && md.Artist.value),
+      licence: strip(md.LicenseShortName && md.LicenseShortName.value),
+      licenceUrl: (md.LicenseUrl && md.LicenseUrl.value) || '',
+      url: ii.thumburl || ii.url,
+      original: ii.url || '',
+      page: ii.descriptionurl || '',
+      width: ii.width || null,
+      height: ii.height || null,
+      mime: ii.mime || '',
+    };
+  }).filter((r) => r.url && /^image\/(jpeg|png|webp|gif)/.test(r.mime || 'image/jpeg'));
+}
+
+export function parseAic(json) {
+  const base = (json.config && json.config.iiif_url) || 'https://www.artic.edu/iiif/2';
+  return (json.data || []).filter((d) => d.image_id && d.is_public_domain === true).map((d) => ({
+    source: 'aic',
+    title: d.title || '',
+    creator: String(d.artist_display || '').split('\n')[0],
+    licence: 'CC0 (public domain)',
+    licenceUrl: 'https://creativecommons.org/publicdomain/zero/1.0/',
+    url: `${base}/${d.image_id}/full/843,/0/default.jpg`,
+    page: `https://www.artic.edu/artworks/${d.id}`,
+    width: (d.thumbnail && d.thumbnail.width) || null,
+    height: (d.thumbnail && d.thumbnail.height) || null,
+  }));
+}
+
+export function parseMetObject(o) {
+  if (!o || o.isPublicDomain !== true || !o.primaryImageSmall) return null;
+  return {
+    source: 'met',
+    title: o.title || '',
+    creator: o.artistDisplayName || '',
+    licence: 'CC0 (Met Open Access)',
+    licenceUrl: 'https://creativecommons.org/publicdomain/zero/1.0/',
+    url: o.primaryImageSmall,
+    original: o.primaryImage || '',
+    page: o.objectURL || `https://www.metmuseum.org/art/collection/search/${o.objectID}`,
+    width: null,
+    height: null,
+  };
+}
+
+async function getJson(url, headers = {}, ms = 20000) {
+  const r = await publicFetch(url, { headers: { 'user-agent': UA, accept: 'application/json', ...headers }, signal: AbortSignal.timeout(ms) });
+  if (!r.ok) { await r.body?.cancel(); throw new Error(`${new URL(url).host} answered ${r.status}`); }
+  return JSON.parse((await readLimited(r, 2 * 1024 * 1024)).toString('utf8'));
+}
+
+export const SEARCH = {
+  async openverse(q, n) {
+    return parseOpenverse(await getJson(`https://api.openverse.org/v1/images/?q=${encodeURIComponent(q)}&page_size=${Math.min(n * 2, 40)}&mature=false`));
+  },
+  async commons(q, n) {
+    const u = 'https://commons.wikimedia.org/w/api.php?action=query&format=json&generator=search&gsrnamespace=6'
+      + `&gsrsearch=${encodeURIComponent(q + ' filetype:bitmap')}&gsrlimit=${Math.min(n * 2, 40)}`
+      + '&prop=imageinfo&iiprop=url|size|mime|extmetadata&iiurlwidth=1280'
+      + '&iiextmetadatafilter=LicenseShortName|LicenseUrl|Artist|ObjectName';
+    return parseCommons(await getJson(u, { 'user-agent': UA_CONTACT }));
+  },
+  async aic(q, n) {
+    const u = `https://api.artic.edu/api/v1/artworks/search?q=${encodeURIComponent(q)}&limit=${Math.min(n * 3, 60)}`
+      + '&fields=id,title,image_id,artist_display,is_public_domain,thumbnail';
+    return parseAic(await getJson(u, { 'AIC-User-Agent': UA_CONTACT }));
+  },
+  async met(q, n) {
+    const s = await getJson(`https://collectionapi.metmuseum.org/public/collection/v1/search?hasImages=true&q=${encodeURIComponent(q)}`);
+    const out = [];
+    for (const id of (s.objectIDs || []).slice(0, n * 4)) {
+      if (out.length >= n * 2) break;
+      try {
+        const r = parseMetObject(await getJson(`https://collectionapi.metmuseum.org/public/collection/v1/objects/${id}`));
+        if (r) out.push(r);
+      } catch {}
+    }
+    return out;
+  },
+};
+
+/* Fetches the URL the way a page would load it. HEAD first; a server that
+   refuses HEAD (405, 403, 416 and friends) gets a one-byte ranged GET. The
+   result counts only if the answer is 2xx and says it is an image. */
+export async function verifyImage(url, { fetchImpl = publicFetch, ms = 15000 } = {}) {
+  try { checkUrl(url); } catch (e) { return { ok: false, status: 0, type: '', error: e.message }; }
+  const tryOnce = async (method) => {
+    const headers = { 'user-agent': UA };
+    if (method === 'GET') headers.range = 'bytes=0-0';
+    const r = await fetchImpl(url, { method, headers, redirect: 'follow', signal: AbortSignal.timeout(ms) });
+    try { if (r.body && r.body.cancel) await r.body.cancel(); } catch {}
+    return { status: r.status, type: (r.headers.get('content-type') || '').split(';')[0].trim().toLowerCase(),
+      url: r.url || url, checkedAt: new Date().toISOString(), evidence: 'response headers only; decode checked when tiled' };
+  };
+  let res;
+  try {
+    res = await tryOnce('HEAD');
+    if (!(res.status >= 200 && res.status < 300 && res.type.startsWith('image/'))) res = await tryOnce('GET');
+  } catch (e) {
+    try { res = await tryOnce('GET'); } catch (e2) { return { ok: false, status: 0, type: '', error: (e2 && e2.message) || String(e2) }; }
+  }
+  return { ok: res.status >= 200 && res.status < 300 && /^image\/(jpeg|png|webp|gif)$/.test(res.type), ...res };
+}
+
+export const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+export function rasterType(bytes) {
+  if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return { type: 'image/png', ext: 'png' };
+  if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return { type: 'image/jpeg', ext: 'jpg' };
+  if (/^GIF8[79]a/.test(bytes.subarray(0, 6).toString('ascii'))) return { type: 'image/gif', ext: 'gif' };
+  if (bytes.length >= 12 && bytes.subarray(0, 4).toString('ascii') === 'RIFF' && bytes.subarray(8, 12).toString('ascii') === 'WEBP') return { type: 'image/webp', ext: 'webp' };
+  return null;
+}
+
+export async function downloadImage(url, { fetchImpl = publicFetch, maxBytes = MAX_IMAGE_BYTES, ms = 30000 } = {}) {
+  checkUrl(url);
+  const response = await fetchImpl(url, { headers: { 'user-agent': UA }, signal: AbortSignal.timeout(ms) });
+  if (!response.ok) { await response.body?.cancel(); throw new Error('HTTP ' + response.status); }
+  const declared = (response.headers.get('content-type') || '').split(';')[0].trim().toLowerCase();
+  if (!/^image\/(jpeg|png|gif|webp)$/.test(declared)) {
+    await response.body?.cancel();
+    throw new Error('unsupported raster image content type: ' + declared);
+  }
+  const bytes = await readLimited(response, maxBytes);
+  const actual = rasterType(bytes);
+  if (!actual || actual.type !== declared) throw new Error('image bytes do not match the declared raster format');
+  return { bytes, ext: actual.ext, url: response.url || url };
+}
+
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (next < items.length) { const i = next++; out[i] = await fn(items[i], i); }
+  }));
+  return out;
+}
+
+export async function searchImages(q, { sources = SOURCES, n = 6, commercial = false, verify = verifyImage } = {}) {
+  const errors = [];
+  const per = await Promise.all(sources.map(async (s) => {
+    try {
+      let rows = await SEARCH[s](q, n);
+      if (commercial) rows = rows.filter((r) => commercialOk(r.licence));
+      return rows.slice(0, n);
+    } catch (e) { errors.push({ source: s, error: (e && e.message) || String(e) }); return []; }
+  }));
+  const results = per.flat();
+  await mapLimit(results, 6, async (r) => { r.verified = await verify(r.url); });
+  numberResults(results);
+  return { query: q, sources, commercial, results, errors };
+}
+
+/* One number per verified result, 1..k in list order, and none for a failed
+   one. The table, the compact lines, the moodboard tiles, the download file
+   names and --pick all use it, so "05" names one image everywhere. Before
+   1.1.0 the table counted failures and the sheet did not, so they parted
+   from the first failed result on. */
+export function numberResults(results) {
+  let k = 0;
+  for (const r of results) {
+    if (r.verified && r.verified.ok) r.n = ++k;
+    else delete r.n;
+  }
+  return results;
+}
+
+const nn = (n) => String(n).padStart(2, '0');
+
+export function formatTable(res) {
+  const lines = [];
+  lines.push(`images  "${res.query}"  ${res.results.filter((r) => r.verified.ok).length} verified of ${res.results.length}`);
+  for (const e of res.errors) lines.push(`  source ${e.source} failed: ${e.error}`);
+  for (const r of res.results) {
+    const mark = r.verified.ok ? 'ok  ' : `FAIL ${r.verified.status || ''}`.padEnd(8);
+    lines.push(`  ${r.verified.ok ? nn(r.n) : '--'} ${mark} [${r.source}] ${r.title.slice(0, 70)}${r.creator ? ' - ' + r.creator.slice(0, 40) : ''}`);
+    lines.push(`       ${r.licence || 'licence not stated'}  ${r.url}`);
+    if (r.page) lines.push(`       page ${r.page}`);
+    if (r.downloadError) lines.push(`       download failed: ${r.downloadError}`);
+  }
+  return lines.join('\n');
+}
+
+/* Squeezes a field for a compact line: one line, no URL, at most max chars. */
+const squeeze = (s, max) => {
+  const t = String(s || '').replace(/\b(https?|ftp):\/\/\S*/gi, '').replace(/\s+/g, ' ').trim();
+  return t.length > max ? t.slice(0, max - 3).trimEnd() + '...' : t;
+};
+
+/* "CC0 (Met Open Access)" -> "CC0": the source already says where it is from,
+   and --pick prints the licence in full. */
+const shortLicence = (l) => squeeze(String(l || '').replace(/\s*\([^)]*\)\s*/g, ' '), 16) || 'licence?';
+
+/* A path the details line can hand to a shell as it is. Git Bash, which
+   Claude Code runs on Windows, eats backslashes (C:\Users -> C:Users), and a
+   space splits the argument; Node reads C:/Users/... on Windows. */
+const shellPath = (p) => {
+  const f = String(p).replace(/\\/g, '/');
+  return /^[\w./:@%+,=-]+$/.test(f) ? f : `"${f}"`;
+};
+
+/* The compact report: a header, one line per verified result, the sheet
+   lines, how many failed, and how to get the rest. Never a URL: those stay in
+   results.json and come out through --pick. */
+export function formatCompact(res, { out, resultsPath = join(out, 'results.json') } = {}) {
+  const good = res.results.filter((r) => r.verified.ok);
+  const lines = [`images "${squeeze(res.query, 80)}" ${good.length}/${res.results.length} verified -> ${out}`];
+  for (const e of res.errors || []) lines.push(`source ${e.source} failed: ${squeeze(e.error, 60)}`);
+  for (const r of good) {
+    const creator = squeeze(r.creator, 24);
+    lines.push(`${nn(r.n)} ${r.source} ${shortLicence(r.licence)} | ${squeeze(r.title, 48) || 'untitled'}${creator ? ' | ' + creator : ''}`);
+  }
+  for (const s of res.sheets || []) {
+    const missing = s.tiles.filter((t) => !t.loaded).map((t) => nn(t.n));
+    lines.push(`sheet ${s.file} ${s.w}x${s.h} ${s.tokens} tok${missing.length ? ` (${missing.join(',')} did not load)` : ''}`);
+  }
+  if (res.sheetError) lines.push('sheet none: ' + squeeze(res.sheetError.split('\n')[0], 100));
+  const downloadsFailed = good.filter((r) => r.downloadError).length;
+  if (downloadsFailed) lines.push(`download failed ${downloadsFailed} (see results.json)`);
+  const failed = res.results.length - good.length;
+  if (failed) lines.push(`failed ${failed} (see results.json)`);
+  if (good.length) lines.push(`details: node images.mjs --pick ${good.slice(0, 2).map((r) => r.n).join(',')} --results ${shellPath(resultsPath)}`);
+  return lines.join('\n');
+}
+
+/* --pick: the full record of chosen results from a saved run, three lines
+   each. Reads results.json only; no network. Throws on a number that is not
+   a verified result of that run. */
+export function formatPick(saved, picks) {
+  const results = numberResults(saved.results || []).filter((r) => r.n);
+  const byN = new Map(results.map((r) => [r.n, r]));
+  const lines = [];
+  for (const n of picks) {
+    const r = byN.get(n);
+    if (!r) throw new Error(`no verified result ${n} in this run (${results.length ? '1-' + results.length : 'none verified'})`);
+    lines.push(`${nn(n)} ${r.title || 'untitled'} | ${r.creator || 'creator not stated'} | ${r.licence || 'licence not stated'}${r.licenceUrl ? ' ' + r.licenceUrl : ''}`);
+    lines.push(`   image ${r.url}${r.file ? '  file ' + r.file : ''}`);
+    lines.push(`   page ${r.page || 'not stated'}`);
+  }
+  return lines.join('\n');
+}
+
+function pick(flags) {
+  const fail = (m) => { console.error('images: ' + m); process.exit(2); };
+  if (!flags.results) fail('--pick needs --results <path to results.json>');
+  let picks;
+  try { picks = String(flags.pick).split(',').map((v) => v.trim()).filter(Boolean).map((v) => int(v, 0, { min: 1, max: 999 })); }
+  catch (e) { fail('--pick ' + e.message); }
+  if (!picks.length) fail('--pick needs numbers, such as --pick 3,7');
+  let saved;
+  try { saved = JSON.parse(readFileSync(flags.results, 'utf8')); }
+  catch (e) { fail(`cannot read ${flags.results}: ${(e && e.code) || (e && e.message) || e}`); }
+  try { console.log(formatPick(saved, picks)); } catch (e) { fail(e.message); }
+}
+
+async function main() {
+  let a;
+  try { a = parseArgs(process.argv.slice(2), { switches: ['commercial', 'sheet', 'download', 'json', 'compact'] }); }
+  catch (e) { console.error('images: ' + e.message); process.exit(2); }
+  const { positional, flags } = a;
+  if (flags.pick !== undefined) return pick(flags);
+  const q = positional.join(' ').trim();
+  if (!q) { console.error('usage: node images.mjs "<query>" [--sources ' + SOURCES.join(',') + '] [--n 6] [--commercial] [--sheet] [--download] [--compact] [--out dir] [--json]\n       node images.mjs --pick 3,7 --results <path to results.json>'); process.exit(2); }
+  const compact = !!flags.compact;
+  const sources = String(flags.sources || SOURCES.join(',')).split(',').map((s) => s.trim()).filter(Boolean);
+  const unknown = sources.filter((s) => !SOURCES.includes(s));
+  if (unknown.length) { console.error(`images: unknown source ${unknown.join(', ')}. Sources: ${SOURCES.join(', ')}`); process.exit(2); }
+  let n;
+  try { n = int(flags.n, compact ? 4 : 6, { min: 1, max: 20 }); } catch (e) { console.error('images: --n ' + e.message); process.exit(2); }
+  const out = resolve(flags.out || join(tmpdir(), 'image-deep-research', 'images-' + new Date().toISOString().replace(/[:.]/g, '-')));
+  mkdirSync(out, { recursive: true });
+
+  const res = await searchImages(q, { sources, n, commercial: !!flags.commercial });
+  const good = res.results.filter((r) => r.verified.ok);
+
+  if ((flags.download || flags.sheet || compact) && good.length) {
+    const dir = join(out, 'images');
+    mkdirSync(dir, { recursive: true });
+    await mapLimit(good, 4, async (r) => {
+      try {
+        const image = await downloadImage(r.url);
+        const file = join(dir, `${nn(r.n)}-${r.source}.${image.ext}`);
+        writeFileSync(file, image.bytes);
+        r.file = file;
+        r.downloaded = { bytes: image.bytes.length, url: image.url, checkedAt: new Date().toISOString() };
+      } catch (e) { r.downloadError = (e && e.message) || String(e); }
+    });
+  }
+
+  if ((flags.sheet || compact) && good.length) {
+    try {
+      if (!good.some((r) => r.file)) throw new Error('no raster files downloaded; see downloadError in results.json');
+      const { withBrowser } = await import('./browser.mjs');
+      const { renderSheets } = await import('./sheet.mjs');
+      res.sheets = await withBrowser((session) => renderSheets(session,
+        good.filter((r) => r.file).map((r) => ({ n: r.n, src: r.file, label: `[${r.source}] ${r.licence} ${r.title}` })), { out, prefix: 'moodboard', fit: 'contain', compact }));
+      for (const sheet of res.sheets) for (const tile of sheet.tiles) {
+        const result = good.find((r) => r.n === tile.n);
+        if (result) result.decoded = tile.loaded;
+      }
+    } catch (e) { res.sheetError = (e && e.message) || String(e); }
+  }
+
+  writeFileSync(join(out, 'results.json'), JSON.stringify(res, null, 2));
+  if (flags.json) { console.log(JSON.stringify(res, null, 2)); }
+  else if (compact) console.log(formatCompact(res, { out }));
+  else {
+    console.log(formatTable(res));
+    if (res.sheets) for (const s of res.sheets) {
+      const missing = s.tiles.filter((t) => !t.loaded).map((t) => t.n);
+      console.log(`  moodboard ${s.file}${missing.length ? '  (tiles ' + missing.join(', ') + ' did not load in the browser)' : ''}`);
+    }
+    if (res.sheetError) console.log('  no moodboard: ' + res.sheetError.split('\n')[0]);
+    console.log('  results: ' + join(out, 'results.json'));
+  }
+  if (!good.length || ((flags.sheet || compact) && !(res.sheets || []).some((s) => s.tiles.some((t) => t.loaded)))) process.exitCode = 1;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main();

package/skills/image-deep-research/scripts/network.mjs

@@ -0,0 +1,104 @@
+/* Public collection responses are untrusted. Resolve every redirect, reject
+   private destinations, and pin the checked address for the actual socket. */
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { Readable } from 'node:stream';
+
+export function publicAddress(address) {
+  if (isIP(address) === 4) {
+    const [a, b, c] = address.split('.').map(Number);
+    return !(a === 0 || a === 10 || a === 127 || a >= 224
+      || (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254)
+      || (a === 172 && b >= 16 && b <= 31) || (a === 192 && (b === 168 || (b === 0 && (c === 0 || c === 2))))
+      || (a === 198 && (b === 18 || b === 19 || (b === 51 && c === 100)))
+      || (a === 203 && b === 0 && c === 113));
+  }
+  if (isIP(address) !== 6) return false;
+  const first = Number.parseInt(address.split(':')[0], 16);
+  const second = Number.parseInt(address.split(':')[1] || '0', 16);
+  // Only global unicast; exclude documentation, transition and special-use ranges.
+  return first >= 0x2000 && first < 0x3fff && first !== 0x2002
+    && !(first === 0x2001 && (second < 0x200 || second === 0xdb8));
+}
+
+export function checkUrl(value) {
+  const u = new URL(value);
+  if (!['https:', 'http:'].includes(u.protocol) || u.username || u.password)
+    throw new Error('image URL must use HTTP(S) without credentials');
+  const hostname = u.hostname.replace(/^\[|\]$/g, '');
+  if (isIP(hostname) && !publicAddress(hostname)) throw new Error('private or special-use image destination blocked');
+  if (hostname === 'localhost' || /\.(?:localhost|local|internal)$/i.test(hostname))
+    throw new Error('private image destination blocked');
+  return u;
+}
+
+export async function publicFetch(value, { method = 'GET', headers = {}, signal,
+  lookupImpl = lookup, requestImpl, maxRedirects = 5 } = {}) {
+  let u = checkUrl(value);
+  for (let redirects = 0; ; redirects++) {
+    signal?.throwIfAborted();
+    const hostname = u.hostname.replace(/^\[|\]$/g, '');
+    let onAbort;
+    const aborted = signal && new Promise((_, reject) => {
+      onAbort = () => reject(signal.reason);
+      signal.addEventListener('abort', onAbort, { once: true });
+    });
+    let addresses;
+    try {
+      const resolving = isIP(hostname) ? Promise.resolve([{ address: hostname, family: isIP(hostname) }])
+        : lookupImpl(hostname, { all: true, verbatim: true });
+      addresses = await (aborted ? Promise.race([resolving, aborted]) : resolving);
+    } finally { if (onAbort) signal.removeEventListener('abort', onAbort); }
+    if (!addresses.length || addresses.some((a) => !publicAddress(a.address)))
+      throw new Error('private or special-use image destination blocked');
+    const chosen = addresses[0];
+    const request = requestImpl || (u.protocol === 'https:' ? httpsRequest : httpRequest);
+    const res = await new Promise((resolve, reject) => {
+      const req = request(u, { method, headers, signal, agent: false,
+        lookup: (_host, options, cb) => cb(null, options?.all ? [chosen] : chosen.address, chosen.family) }, resolve);
+      req.once('error', reject);
+      req.end();
+    });
+    const responseHeaders = new Headers();
+    for (const [name, val] of Object.entries(res.headers)) {
+      if (val !== undefined) responseHeaders.set(name, Array.isArray(val) ? val.join(', ') : String(val));
+    }
+    const status = res.statusCode;
+    const location = responseHeaders.get('location');
+    if ([301, 302, 303, 307, 308].includes(status) && location) {
+      res.destroy();
+      if (redirects >= maxRedirects) throw new Error('too many image redirects');
+      u = checkUrl(new URL(location, u).href);
+      continue;
+    }
+    const response = new Response(method === 'HEAD' || [204, 205, 304].includes(status) ? null : Readable.toWeb(res),
+      { status, headers: responseHeaders });
+    if (method === 'HEAD') res.destroy();
+    Object.defineProperty(response, 'url', { value: u.href });
+    return response;
+  }
+}
+
+export async function readLimited(response, maxBytes) {
+  const declared = Number(response.headers.get('content-length'));
+  if (declared > maxBytes) {
+    await response.body?.cancel();
+    throw new Error(`response exceeds ${maxBytes} bytes`);
+  }
+  const reader = response.body?.getReader();
+  if (!reader) return Buffer.alloc(0);
+  const parts = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > maxBytes) throw new Error(`response exceeds ${maxBytes} bytes`);
+      parts.push(Buffer.from(value));
+    }
+    return Buffer.concat(parts, size);
+  } finally { await reader.cancel().catch(() => {}); }
+}

package/skills/image-deep-research/scripts/sheet.mjs

@@ -0,0 +1,168 @@
+/* image-deep-research/sheet - tile pictures into one contact sheet.
+
+   The browser does the tiling: a small HTML page lays the images out on a
+   4 x 2 grid, each cell numbered, and the page is screenshotted. No ffmpeg,
+   no image codec, and it works the same for local screenshots and for remote
+   image URLs (a moodboard). One sheet costs one image read instead of eight.
+
+   --compact draws a denser sheet, sized for what a Claude model pays: 16
+   tiles with a number badge and no caption row, 1288 x 812 px, which is
+   46 x 29 patches of 28 px, 1,334 image tokens, under every model's cap. */
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join, relative, isAbsolute, dirname, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { load, screenshot } from './browser.mjs';
+
+export const PER_SHEET = 8;
+export const COLS = 4;
+export const CELL_W = 640;
+export const CELL_H = 400;
+
+/* The compact geometry: 4 x 4 cells of 317 x 198 with a 4 px gap and pad. */
+export const COMPACT = { cols: 4, perSheet: 16, cellW: 317, cellH: 198, gap: 4, pad: 4 };
+export const COMPACT_MAX_BYTES = 150000;
+export const COMPACT_QUALITIES = [80, 70, 60];
+
+/* What an image costs a Claude model, as Anthropic's vision docs price it
+   (platform.claude.com/docs/en/build-with-claude/vision, read 2026-09-29):
+   ceil(w/28) x ceil(h/28) tokens, after the image is scaled down, keeping its
+   aspect ratio, to the largest size that fits both the tier's long edge and
+   its token cap. The high tier (Claude 4.7 and later) allows a 2576 px long
+   edge and 4,784 tokens; the standard tier 1568 px and 1,568 tokens. */
+export const PATCH = 28;
+export const TIERS = { high: { edge: 2576, cap: 4784 }, standard: { edge: 1568, cap: 1568 } };
+
+export function visionTokens(w, h, { tier = 'high' } = {}) {
+  const t = TIERS[tier];
+  if (!t) throw new Error(`unknown tier "${tier}"`);
+  const cost = (W, H) => Math.ceil(W / PATCH) * Math.ceil(H / PATCH);
+  const long = Math.max(w, h);
+  const at = (edge) => {
+    const s = edge / long;
+    return [Math.max(1, Math.round(w * s)), Math.max(1, Math.round(h * s))];
+  };
+  let edge = Math.min(long, t.edge);
+  if (cost(...at(edge)) > t.cap) {
+    // The cost only grows with the long edge, so the largest edge that fits
+    // the cap is found by halving the interval.
+    let lo = 1, hi = edge;
+    while (lo < hi) {
+      const mid = Math.ceil((lo + hi) / 2);
+      if (cost(...at(mid)) <= t.cap) lo = mid; else hi = mid - 1;
+    }
+    edge = lo;
+  }
+  return cost(...at(edge));
+}
+
+/* The pixel size of a sheet of count tiles in a badge-only geometry. */
+export function sheetSize(count, geom = COMPACT) {
+  const cols = Math.max(1, Math.min(geom.cols, count));
+  const rows = Math.max(1, Math.ceil(count / geom.cols));
+  const w = 2 * geom.pad + cols * geom.cellW + (cols - 1) * geom.gap;
+  const h = 2 * geom.pad + rows * geom.cellH + (rows - 1) * geom.gap;
+  return { w, h, tokens: visionTokens(w, h) };
+}
+
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+
+/* Splits items into sheets of PER_SHEET, numbering every tile across the run
+   so "tile 11" means the same thing in the sheet and in the printed legend.
+   An item that already carries its number keeps it: images.mjs numbers the
+   verified results, and a failed one before them must not shift the tiles. */
+export function planSheets(items, per = PER_SHEET) {
+  const sheets = [];
+  items.forEach((item, i) => {
+    const s = Math.floor(i / per);
+    (sheets[s] ||= []).push({ ...item, n: item.n ?? i + 1 });
+  });
+  return sheets;
+}
+
+/* The HTML for one sheet. src is a URL, or a local path that is written
+   relative to the sheet so the page can load it from disk. */
+export function sheetHtml(tiles, { baseDir, fit = 'cover', title = '', compact = false } = {}) {
+  const src = (s) => {
+    if (/^(https?|data):/i.test(s)) return s;
+    const p = isAbsolute(s) ? s : resolve(s);
+    return relative(baseDir, p).split(sep).map(encodeURIComponent).join('/');
+  };
+  if (compact) return compactHtml(tiles, { src, fit, title });
+  const cells = tiles.map((t) => `<figure><img src="${esc(src(t.src))}" alt="" referrerpolicy="no-referrer"><figcaption>${String(t.n).padStart(2, '0')}  ${esc(t.label || '')}</figcaption></figure>`).join('\n');
+  return `<!doctype html><meta charset="utf-8"><title>${esc(title)}</title>
+<style>
+html,body{margin:0;background:#111}
+main{display:grid;grid-template-columns:repeat(${Math.max(1, Math.min(COLS, tiles.length))},${CELL_W}px);gap:6px;padding:6px;width:max-content}
+figure{margin:0;background:#1b1b1b}
+img{display:block;width:${CELL_W}px;height:${CELL_H}px;object-fit:${fit === 'contain' ? 'contain' : 'cover'};object-position:${fit === 'contain' ? 'center' : 'top center'}}
+figcaption{font:13px/1.2 ui-monospace,Consolas,monospace;color:#ddd;padding:4px 6px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;width:${CELL_W - 12}px}
+</style>
+<main>
+${cells}
+</main>`;
+}
+
+/* The compact sheet: no caption row, only the tile's number on a dark badge
+   in its top-left corner (or the tile's own badge text, such as s03 for a
+   site). Every other fact about a tile goes out as text. */
+function compactHtml(tiles, { src, fit, title }) {
+  const g = COMPACT;
+  const cells = tiles.map((t) => `<figure><img src="${esc(src(t.src))}" alt="" referrerpolicy="no-referrer"><span>${esc(t.badge ?? String(t.n).padStart(2, '0'))}</span></figure>`).join('\n');
+  return `<!doctype html><meta charset="utf-8"><title>${esc(title)}</title>
+<style>
+html,body{margin:0;background:#111}
+main{display:grid;grid-template-columns:repeat(${Math.max(1, Math.min(g.cols, tiles.length))},${g.cellW}px);gap:${g.gap}px;padding:${g.pad}px;width:max-content}
+figure{margin:0;position:relative;background:#1b1b1b;width:${g.cellW}px;height:${g.cellH}px}
+img{display:block;width:${g.cellW}px;height:${g.cellH}px;object-fit:${fit === 'contain' ? 'contain' : 'cover'};object-position:${fit === 'contain' ? 'center' : 'top center'}}
+span{position:absolute;top:0;left:0;font:12px/1 ui-monospace,Consolas,monospace;color:#fff;background:rgba(0,0,0,.7);padding:2px 4px}
+</style>
+<main>
+${cells}
+</main>`;
+}
+
+/* Takes a picture at each quality in turn until one is at most maxBytes, so a
+   busy sheet still fits a Read without a silent downscale. shoot(quality)
+   returns the JPEG bytes. The last quality is kept even when it is over. */
+export async function underBytes(shoot, { maxBytes = COMPACT_MAX_BYTES, qualities = COMPACT_QUALITIES } = {}) {
+  let buf, quality;
+  for (quality of qualities) {
+    buf = await shoot(quality);
+    if (buf.length <= maxBytes) break;
+  }
+  return { buf, quality };
+}
+
+/* Renders every sheet with an open browser session. Returns
+   [{ file, tiles: [{n, label, src, loaded}] }]. A tile whose image failed to
+   load is reported as loaded:false rather than silently left grey. With
+   compact, sixteen to a sheet in the compact geometry, and each sheet also
+   reports { w, h, bytes, quality, tokens }. */
+export async function renderSheets(session, items, { out, prefix = 'sheet', fit = 'cover', per, compact = false } = {}) {
+  mkdirSync(out, { recursive: true });
+  per ??= compact ? COMPACT.perSheet : PER_SHEET;
+  const results = [];
+  for (const [i, tiles] of planSheets(items, per).entries()) {
+    const html = join(out, `_${prefix}${i + 1}.html`);
+    writeFileSync(html, sheetHtml(tiles, { baseDir: dirname(html), fit, title: `${prefix} ${i + 1}`, compact }));
+    const width = compact ? sheetSize(COMPACT.cols, COMPACT).w : COLS * (CELL_W + 6) + 6;
+    await load(session, pathToFileURL(html).href, { width, height: 900, wait: 200 });
+    const state = await session.evaluate(`Promise.all([...document.images].map((im) =>
+      im.complete ? 0 : new Promise((r) => { im.onload = im.onerror = r; setTimeout(r, 15000); })))
+      .then(() => { const m = document.querySelector('main').getBoundingClientRect();
+        return { w: Math.ceil(m.width), h: Math.ceil(m.height), ok: [...document.images].map((im) => im.naturalWidth > 0) }; })`, { awaitPromise: true });
+    const file = join(out, `${prefix}${i + 1}.jpg`);
+    const clip = { x: 0, y: 0, width: state.w, height: state.h };
+    const shown = tiles.map((t, k) => ({ n: t.n, label: t.label, src: t.src, loaded: !!state.ok[k] }));
+    if (!compact) {
+      writeFileSync(file, await screenshot(session, { format: 'jpeg', quality: 84, clip }));
+      results.push({ file, tiles: shown });
+      continue;
+    }
+    const { buf, quality } = await underBytes((q) => screenshot(session, { format: 'jpeg', quality: q, clip }));
+    writeFileSync(file, buf);
+    results.push({ file, w: state.w, h: state.h, bytes: buf.length, quality, tokens: visionTokens(state.w, state.h), tiles: shown });
+  }
+  return results;
+}