image-deep-research 0.0.0-stage → 1.2.0

package/skills/image-deep-research/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: image-deep-research
+description: Image deep research and visual research - use when a question is better answered by looking than by reading. Finds reference images on open, licensed collections (Openverse, Wikimedia Commons, the Art Institute of Chicago, the Met), renders real websites into screenshot contact sheets, builds a moodboard, measures a live site's palette and typefaces, and reads every picture as a picture. For design references, styles, palettes, typefaces, materials, competitors and moodboards.
+argument-hint: "<topic, style, palette, typeface, competitor list, or URLs to look at>"
+---
+
+# Image deep research
+
+Most design questions are answered by looking at twenty examples, not by
+reading one article about them. This skill gets the pictures in front of you
+cheaply, checks that they are real, keeps the licence beside every one, and
+then makes you read them before you say anything about them.
+
+The request is whatever the user typed with the skill. If it is empty, ask one
+question: what should be looked at.
+
+## Where the scripts are
+
+The scripts live in `scripts/` next to this file. In Claude Code that folder
+is `${CLAUDE_SKILL_DIR}/scripts`. In Codex, or anywhere that variable comes
+through empty, use the `scripts` folder beside this SKILL.md. They need Node 22
+or newer and nothing else; rendering needs Chrome, Edge or Chromium (set
+`IDR_BROWSER` to the executable if it is somewhere unusual). The browser runs
+headless and never opens a window.
+
+## The loop
+
+Deep research here means rounds, not one search:
+
+1. **Write the question down** in a form a picture can answer. "What do
+   luxury watch sites look like" produces mush; "what ground colour, what
+   headline size, and what the first screen shows on six luxury watch sites"
+   produces numbers you can build with.
+2. **Gather** from the two sources below: real sites for how a thing is done
+   on the web, open collections for subjects, palettes, materials and art.
+3. **Read the contact sheets**, then only the two or three individual images
+   worth a closer look. A sheet of eight costs one read instead of eight.
+   In a coding session or for a first look, add `--compact` to either
+   script: one sheet of up to 16 numbered tiles, 1288x812 and at most 1,334
+   image tokens on any Claude model, one text line per result or site, no
+   URLs (`images.mjs --pick 3,7 --results <path>` prints the ones you keep).
+   Open a single image only for what the sheet and the numbers cannot answer.
+4. **Refine and go again.** The first round tells you the right words: the
+   name of the style, the photographer, the typeface, the movement. Search
+   again with them. Stop when a new round stops changing the answer.
+5. **Report** (see the end of this file).
+
+## Render real sites - the highest-signal source
+
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/study.mjs" <url> <url> ...
+node "${CLAUDE_SKILL_DIR}/scripts/study.mjs" --list editorial
+```
+
+Each site is rendered in a headless browser at the top and one screen down
+(`--scroll 0,900`, `--width 390` for phones, `--reduced-motion` for comparison), tiled into contact sheets
+eight to a sheet, and measured: ground colours by element area (overlaps can count twice), text
+colours by amount of text, and the heading and body typefaces as the browser
+computed them. The measurements print per site and land in `report.json`
+beside the sheets. Curated lists: `editorial`, `object`, `cinema`, `product`.
+Shots record viewport, scroll, time and motion preference; stills do not prove motion.
+
+Two things it cannot see, and it says so rather than guessing: a page that
+answers with a bot challenge or Access Denied, or renders next to nothing (a
+preloader, an empty script shell), is reported as a wall with the reason and
+kept off the sheet; and a canvas-heavy page is flagged, because its
+screenshot may be a preloader frame. For those, try the `y900`
+tile, a longer `--wait 8000`, or a video walkthrough of the site.
+
+## Find images on open collections
+
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/images.mjs" "<query>" --sheet
+node "${CLAUDE_SKILL_DIR}/scripts/images.mjs" "<query>" --commercial --download --sources openverse,commons
+```
+
+Searches Openverse (Creative Commons and public-domain images from Flickr,
+museums and more), Wikimedia Commons, the Art Institute of Chicago (public
+domain works only) and the Met (Open Access works only). No keys. Every result
+URL is fetched before it is reported, and one that does not answer with an
+image is marked FAIL and never put on the moodboard. `--commercial` keeps only
+licences that allow commercial use and changes (it drops NC and ND). `--sheet`
+tiles the verified images into a numbered moodboard; `--download` saves them.
+Results, with title, creator, licence, licence URL and source page, go to
+`results.json`.
+URL checks cover headers, not rights. Sheets cache bounded rasters; read source licences.
+
+Unsplash and Pexels need a free key for their APIs; with one, their CDN URLs
+can be used directly. Check them the same way: an image URL is not a result
+until it has answered with an image.
+
+## Design galleries, for finding sites worth rendering
+
+Awwwards, Godly, Land-book, SiteInspire, Minimal Gallery, Curated.design,
+One Page Love. Fetch the gallery page, pull out the outbound site URLs, then
+render them with `study.mjs`. A gallery's own thumbnails are small and
+colour-shifted: render the real site instead.
+
+## Inside Ultimate Frontend Skills
+
+This skill also ships inside the Ultimate Frontend Skills plugin. When
+`${CLAUDE_PLUGIN_ROOT}/scripts/webdesign.mjs` exists (in Codex: a
+`scripts/webdesign.mjs` in the plugin folder that holds `.codex-plugin/`),
+there is a corpus of award-winning sites to pick references from by
+technique:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/webdesign.mjs" awards "<topic>" --verbose
+node "${CLAUDE_PLUGIN_ROOT}/scripts/webdesign.mjs" study --awards "<topic>" --n 6
+```
+
+When that file is not there, this is the standalone plugin: skip this
+section and find sites through the galleries above.
+
+## Reading what you got
+
+Go in with the question from step 1. Worth extracting every time: the type
+pairing and sizes, the ground colours, where the accent appears, section
+rhythm, what the first screen does, and the one move you have not seen before.
+The `report.json` numbers are what the browser computed; the sheet is what a
+person sees. Use both, and say which one a claim comes from.
+
+## Report
+
+- The file paths of the contact sheets and the moodboard.
+- Every image you recommend with its verified URL, creator, licence and
+  source page. Nothing without a licence goes in a deliverable.
+- Per reference, the one concrete move worth taking, with the number
+  (a colour, a size, a spacing) when there is one.
+- What could not be seen (walls, preloaders, failed URLs), said plainly.
+
+## Do not
+
+Do not describe an image you have not opened. Do not treat a gallery thumbnail
+as evidence of colour. Do not conclude a site uses a library because the
+effect looks like it - check the bundle. Do not ship an image whose licence
+you have not read, and do not drop the attribution a CC BY licence requires.

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

@@ -0,0 +1,27 @@
+/* A small flag parser shared by the scripts: `--name value`, `--name=value`
+   and bare `--switch`. A value flag with nothing after it is a usage error,
+   reported as one line rather than a stack trace. */
+export function parseArgs(argv, { switches = [] } = {}) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--') || a === '--') { positional.push(a); continue; }
+    const eq = a.indexOf('=');
+    const name = a.slice(2, eq === -1 ? undefined : eq);
+    if (eq !== -1) { flags[name] = a.slice(eq + 1); continue; }
+    if (switches.includes(name)) { flags[name] = true; continue; }
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) throw new Error(`--${name} needs a value`);
+    flags[name] = next;
+    i++;
+  }
+  return { positional, flags };
+}
+
+export const int = (v, fallback, { min = -Infinity, max = Infinity } = {}) => {
+  if (v === undefined) return fallback;
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < min || n > max) throw new Error(`expected a whole number between ${min} and ${max}, got "${v}"`);
+  return n;
+};

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

@@ -0,0 +1,300 @@
+/* image-deep-research/browser - find, start and drive a headless Chrome,
+   Edge or Chromium over the DevTools protocol, with no dependencies.
+
+   Vendored from Ultimate Frontend Skills scripts/inspect.mjs (MIT, Gev,
+   github.com/ridelink0/ultimate-frontend-skills): findBrowser, readPortFile,
+   the port handshake in launch() and the Session class are the same code,
+   trimmed to what a screenshot needs. The fixes they carry are kept, because
+   each one was a real failure there: the half-written DevToolsActivePort file,
+   Edge 153 no longer writing that file at all, and the launcher that hands the
+   browser to a child and exits.
+
+   The browser runs --headless=new, so it never opens a window on anyone's
+   screen. Needs Node 22+ for the built-in WebSocket. */
+
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { tmpdir, homedir } from 'node:os';
+import { createServer } from 'node:net';
+
+function candidates(platform, env) {
+  return platform === 'win32'
+    ? [
+        `${env.PROGRAMFILES}\\Google\\Chrome\\Application\\chrome.exe`,
+        `${env['PROGRAMFILES(X86)']}\\Google\\Chrome\\Application\\chrome.exe`,
+        `${env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`,
+        `${env['PROGRAMFILES(X86)']}\\Microsoft\\Edge\\Application\\msedge.exe`,
+        `${env.PROGRAMFILES}\\Microsoft\\Edge\\Application\\msedge.exe`,
+      ]
+    : platform === 'darwin'
+      ? ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+         '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+         '/Applications/Chromium.app/Contents/MacOS/Chromium']
+      : ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium',
+         '/usr/bin/chromium-browser', '/usr/bin/microsoft-edge', '/snap/bin/chromium'];
+}
+
+/* The Chromium builds Playwright downloads, newest revision first in each
+   folder: $PLAYWRIGHT_BROWSERS_PATH, the per-user cache, and /opt/pw-browsers,
+   where containers and cloud sandboxes (this repo's own test container among
+   them, 2026-09-29) keep one and nothing else. Up to Playwright 1.56 the
+   binary sits in chrome-linux/; later ones install Chrome for Testing into
+   chrome-linux64/ (x64) or chrome-linux-arm64/ (read from playwright-core
+   1.56.1 and 1.63.0's registries). */
+const PW_LAYOUTS = ['chrome-linux', 'chrome-linux64', 'chrome-linux-arm64'];
+
+function playwrightChromes({ env, home, readdir }) {
+  const bases = [env.PLAYWRIGHT_BROWSERS_PATH, home && posix.join(home, '.cache', 'ms-playwright'), '/opt/pw-browsers'];
+  const out = [];
+  for (const base of [...new Set(bases.filter(Boolean))]) {
+    let names;
+    try { names = readdir(base); } catch { continue; }
+    const revs = names.map((n) => /^chromium-(\d+)$/.exec(n)).filter(Boolean).sort((a, b) => b[1] - a[1]);
+    for (const m of revs) for (const d of PW_LAYOUTS) out.push(posix.join(base, m[0], d, 'chrome'));
+  }
+  return out;
+}
+
+/* IDR_BROWSER names the executable. ATELIER_BROWSER is the variable Ultimate
+   Frontend Skills reads, honoured too so one setting serves both. Everything
+   the lookup touches can be injected, so a test can stand in a file system. */
+export function findBrowser({ env = process.env, platform = process.platform, home = homedir(),
+  exists = existsSync, readdir = (d) => readdirSync(d) } = {}) {
+  for (const v of ['IDR_BROWSER', 'ATELIER_BROWSER']) {
+    const p = env[v];
+    if (p && exists(p)) return p;
+  }
+  const found = candidates(platform, env).find((p) => p && exists(p));
+  if (found) return found;
+  if (platform !== 'linux') return null;
+  return playwrightChromes({ env, home, readdir }).find((p) => exists(p)) || null;
+}
+
+/* Chrome refuses to start as root unless its sandbox is switched off, and
+   exits before it opens a debugging port (measured in a root container,
+   2026-09-29). So --no-sandbox goes in for root, or when IDR_NO_SANDBOX=1
+   asks for it, and never otherwise. */
+export function launchArgs(udd, port, { uid = process.getuid?.(), env = process.env } = {}) {
+  // --disable-component-update: a fresh profile starts Edge's component
+  // updater, which leaves msedge_url_fetcher_* folders in TEMP.
+  return [
+    '--headless=new', '--hide-scrollbars', '--mute-audio',
+    '--no-first-run', '--no-default-browser-check', '--disable-extensions',
+    '--disable-background-networking', '--disable-component-update', '--disable-sync', '--disable-features=Translate',
+    ...(uid === 0 || env.IDR_NO_SANDBOX === '1' ? ['--no-sandbox'] : []),
+    `--user-data-dir=${udd}`, `--remote-debugging-port=${port}`, 'about:blank',
+  ];
+}
+
+export const NO_BROWSER = 'no Chrome, Edge or Chromium found.\n'
+  + '  Windows: Edge is usually already installed; or winget install Google.Chrome\n'
+  + '  macOS:   brew install --cask google-chrome\n'
+  + '  Linux:   apt-get install chromium\n'
+  + 'Or set IDR_BROWSER to the browser executable.';
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/* Chrome creates DevToolsActivePort before it writes the port into it, so the
+   file can exist and be empty, half-written, or (on Windows) locked. All of
+   those mean "not yet". Returns the port, or null to keep waiting. */
+export function readPortFile(path) {
+  let first;
+  try { first = readFileSync(path, 'utf8').split('\n')[0].trim(); } catch { return null; }
+  const port = Number(first);
+  return Number.isInteger(port) && port > 0 && port < 65536 ? port : null;
+}
+
+function freePort() {
+  return new Promise((res, rej) => {
+    const s = createServer();
+    s.once('error', rej);
+    s.listen(0, '127.0.0.1', () => { const { port } = s.address(); s.close(() => res(port)); });
+  });
+}
+
+async function answers(port) {
+  try { return (await fetch(`http://127.0.0.1:${port}/json/version`, { signal: AbortSignal.timeout(500) })).ok; }
+  catch { return false; }
+}
+
+/* The browser's own temp directory, inside the profile that close() deletes.
+   Edge leaves an Importer_0_4 folder and cv_debug.log in the TEMP it inherits
+   whenever a page makes a network request, outside the profile where no
+   profile delete reaches them; with --disable-component-update missing it also
+   left msedge_url_fetcher_* folders (Ultimate Frontend Skills judge, round 3,
+   2026-09-27). Any casing of the variable is replaced: Windows reads TEMP and
+   Temp as one name. */
+function browserEnv(dir) {
+  const env = {};
+  for (const [k, v] of Object.entries(process.env)) if (!/^(TEMP|TMP|TMPDIR)$/i.test(k)) env[k] = v;
+  return { ...env, TEMP: dir, TMP: dir, TMPDIR: dir };
+}
+
+/* Starts the browser and resolves once DevTools answers. The returned close()
+   asks the browser to quit over the protocol first, waits for it to stop
+   answering, and only then falls back to ending the processes that carry this
+   run's own temporary profile - never any other browser the user has open. */
+export async function launch(bin = findBrowser()) {
+  if (!bin) { const e = new Error(NO_BROWSER); e.code = 'no-browser'; throw e; }
+  if (typeof WebSocket === 'undefined') throw new Error('image-deep-research needs Node 22 or newer (built-in WebSocket).');
+  const udd = mkdtempSync(join(tmpdir(), 'idr-cdp-'));
+  const ownTmp = join(udd, 'tmp');
+  mkdirSync(ownTmp);
+  const asked = await freePort();
+  const proc = spawn(bin, launchArgs(udd, asked), { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: true, env: browserEnv(ownTmp) });
+  let launchError;
+  proc.once('error', (err) => { launchError = err; });
+
+  const portFile = join(udd, 'DevToolsActivePort');
+  // 45 s, not 15: the first start of Chrome on a fresh Windows machine (a CI
+  // runner, measured 2026-09-25) took longer than 15 s to open its port, while
+  // every later start in the same run took about one.
+  const deadline = Date.now() + 45000;
+  for (let i = 0; Date.now() < deadline; i++) {
+    if (launchError || (proc.exitCode !== null && proc.exitCode !== 0)) break;
+    const port = readPortFile(portFile) || (i % 3 === 2 && await answers(asked) ? asked : null);
+    if (port) return { port, udd, close: () => shutdown(proc, udd, port) };
+    await sleep(100);
+  }
+  await shutdown(proc, udd, asked);
+  throw new Error(launchError ? 'browser launch failed: ' + launchError.message : 'browser did not expose a debugging port');
+}
+
+async function shutdown(proc, udd, port) {
+  try {
+    const v = await (await fetch(`http://127.0.0.1:${port}/json/version`, { signal: AbortSignal.timeout(1500) })).json();
+    await new Promise((res) => {
+      const ws = new WebSocket(v.webSocketDebuggerUrl);
+      const done = () => { try { ws.close(); } catch {} res(); };
+      ws.addEventListener('open', () => { try { ws.send(JSON.stringify({ id: 1, method: 'Browser.close' })); } catch {} setTimeout(done, 300); });
+      ws.addEventListener('error', done);
+      setTimeout(done, 2000);
+    });
+  } catch {}
+  for (let i = 0; i < 30 && await answers(port); i++) await sleep(100);
+  if (proc.exitCode === null) { try { proc.kill(); } catch {} }
+  // Helper processes (the crash handler, a utility process) can outlive the
+  // browser and hold the profile folder open for seconds. Wait for them first;
+  // only if the folder is still locked, end the processes started with this
+  // run's own temporary profile on their command line, and no other.
+  if (await removeProfile(udd, 3000) || process.platform !== 'win32') return;
+  endProfileProcesses(udd);
+  await removeProfile(udd, 5000);
+}
+
+async function removeProfile(udd, ms) {
+  const until = Date.now() + ms;
+  for (;;) {
+    try { rmSync(udd, { recursive: true, force: true }); } catch {}
+    if (!existsSync(udd)) return true;
+    if (Date.now() > until) return false;
+    await sleep(250);
+  }
+}
+
+function endProfileProcesses(udd) {
+  const q = udd.replace(/'/g, "''");
+  spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command',
+    `Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -and $_.CommandLine.Contains('${q}') } | ForEach-Object { try { Stop-Process -Id $_.ProcessId -Force -ErrorAction Stop } catch {} }`],
+  { stdio: 'ignore', windowsHide: true, timeout: 15000 });
+}
+
+export class Session {
+  constructor(ws) { this.ws = ws; this.id = 0; this.waiting = new Map(); this.events = []; }
+  static async open(port) {
+    let target;
+    for (let i = 0; i < 60 && !target; i++) {
+      try {
+        const list = await (await fetch(`http://127.0.0.1:${port}/json/list`)).json();
+        target = list.find((t) => t.type === 'page' && t.webSocketDebuggerUrl);
+      } catch {}
+      if (!target) await sleep(100);
+    }
+    if (!target) throw new Error('no page target');
+    const ws = new WebSocket(target.webSocketDebuggerUrl);
+    await new Promise((res, rej) => {
+      ws.addEventListener('open', res, { once: true });
+      ws.addEventListener('error', () => rej(new Error('cdp socket failed')), { once: true });
+    });
+    const s = new Session(ws);
+    ws.addEventListener('message', (e) => {
+      const msg = JSON.parse(e.data);
+      if (msg.id && s.waiting.has(msg.id)) {
+        const { res, rej, timer } = s.waiting.get(msg.id);
+        clearTimeout(timer);
+        s.waiting.delete(msg.id);
+        msg.error ? rej(new Error(msg.error.message)) : res(msg.result);
+      } else if (msg.method) { s.events.push(msg); if (s.events.length > 2000) s.events.shift(); }
+    });
+    ws.addEventListener('close', () => s.failPending(new Error('CDP connection closed')));
+    return s;
+  }
+  failPending(error) {
+    for (const { rej, timer } of this.waiting.values()) { clearTimeout(timer); rej(error); }
+    this.waiting.clear();
+  }
+  send(method, params = {}, ms = 45000) {
+    const id = ++this.id;
+    return new Promise((res, rej) => {
+      const timer = setTimeout(() => {
+        if (this.waiting.has(id)) { this.waiting.delete(id); rej(new Error(method + ' timed out')); }
+      }, ms);
+      this.waiting.set(id, { res, rej, timer });
+      try { this.ws.send(JSON.stringify({ id, method, params })); }
+      catch (err) { clearTimeout(timer); this.waiting.delete(id); rej(err); }
+    });
+  }
+  async waitForEvent(method, ms = 25000) {
+    const t0 = Date.now();
+    while (Date.now() - t0 < ms) {
+      const i = this.events.findIndex((e) => e.method === method);
+      if (i !== -1) return this.events.splice(i, 1)[0];
+      await sleep(50);
+    }
+    return null;
+  }
+  async evaluate(expression, { awaitPromise = false } = {}) {
+    const r = await this.send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise });
+    if (r.exceptionDetails) throw new Error('page script failed: ' + (r.exceptionDetails.exception?.description || r.exceptionDetails.text));
+    return r.result?.value;
+  }
+  close() { this.failPending(new Error('CDP session closed')); try { this.ws.close(); } catch {} }
+}
+
+/* One browser for a whole run: starts it, hands fn a page session, and
+   always shuts the browser down afterwards, even when fn throws. */
+export async function withBrowser(fn) {
+  const b = await launch();
+  let session;
+  try {
+    session = await Session.open(b.port);
+    await session.send('Page.enable');
+    await session.send('Runtime.enable');
+    return await fn(session);
+  } finally {
+    if (session) session.close();
+    await b.close();
+  }
+}
+
+/* Loads a URL (or a data: / file: page) at a viewport and waits for it to
+   settle: the load event, web fonts, then a fixed pause for entrance motion. */
+export async function load(session, url, { width = 1440, height = 900, wait = 3000, timeout = 30000 } = {}) {
+  await session.send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: width < 700 });
+  session.events.length = 0;
+  const nav = await session.send('Page.navigate', { url });
+  if (nav.errorText) throw new Error('navigation failed: ' + nav.errorText);
+  const loaded = await session.waitForEvent('Page.loadEventFired', timeout);
+  await session.evaluate('document.fonts ? document.fonts.ready.then(() => 1) : 1', { awaitPromise: true }).catch(() => {});
+  await sleep(wait);
+  return { loaded: !!loaded };
+}
+
+export async function screenshot(session, { format = 'png', quality, clip } = {}) {
+  const params = { format, captureBeyondViewport: !!clip };
+  if (format === 'jpeg') params.quality = quality ?? 82;
+  if (clip) params.clip = { ...clip, scale: 1 };
+  const r = await session.send('Page.captureScreenshot', params);
+  return Buffer.from(r.data, 'base64');
+}