@yojahny/wp-design-library 0.3.0 → 0.5.1

package/src/cli/motion.mjs

@@ -0,0 +1,168 @@
+// Repository-only authoring command. Playback and MCP readers do not need ffmpeg or R2 credentials.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import yaml from 'js-yaml';
+import sharp from 'sharp';
+import { paths } from '../paths.mjs';
+import { parseEntry } from '../entry.mjs';
+import { isHttpsUrl, localMotionPath, validateMotion } from '../motion.mjs';
+
+const ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function probe(file) {
+  const info = JSON.parse(execFileSync('ffprobe', ['-v', 'error', '-select_streams', 'v:0',
+    '-show_entries', 'format=duration:stream=width,height,r_frame_rate', '-of', 'json', file], { encoding: 'utf8' }));
+  if (!info.streams?.[0]) throw new Error('input has no video stream');
+  return { ...info.streams[0], duration: Number(info.format?.duration) };
+}
+function ffmpeg(args) {
+  try { execFileSync('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-nostdin', ...args], { stdio: ['ignore', 'pipe', 'pipe'] }); }
+  catch (e) { throw new Error(`ffmpeg: ${e.stderr?.toString().trim() || e.message}`); }
+}
+function writeEntry(entry) {
+  const file = path.join(entry.dir, 'entry.md');
+  const tmp = `${file}.motion-tmp`;
+  fs.writeFileSync(tmp, `---\n${yaml.dump(entry.fm, { lineWidth: 110, noRefs: true })}---\n\n${entry.body}\n`);
+  fs.renameSync(tmp, file);
+}
+function entryFor(p, slug) {
+  if (!ID.test(slug)) throw new Error('a valid --slug is required');
+  return parseEntry(path.join(p.entries, slug));
+}
+
+export async function prepareMotion({ p = paths(), slug, input, id, title, notes, capture = 1, start = 0, duration = 15 }) {
+  const entry = entryFor(p, slug);
+  if (!ID.test(id) || !title?.trim() || !notes?.trim()) throw new Error('--id, --title and --notes are required');
+  if ((entry.fm.motion?.clips ?? []).some((c) => c.id === id)) throw new Error(`clip ${id} already exists; choose a new id`);
+  if (!Number.isInteger(capture) || capture < 1 || capture > (entry.fm.captured?.captures?.length ?? 1)) throw new Error('--capture must name an existing capture');
+  if (!Number.isFinite(start) || start < 0 || !Number.isFinite(duration) || duration <= 0 || duration > 15) throw new Error('--start must be nonnegative and --duration must be 0–15 seconds');
+  const source = fs.realpathSync(input);
+  if (!fs.statSync(source).isFile()) throw new Error('input must be a local video file');
+  const info = probe(source);
+  if (Number.isFinite(info.duration) && start >= info.duration) throw new Error('--start is beyond the video');
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'library-motion-'));
+  const evidenceDir = path.join(entry.dir, 'motion', id);
+  if (fs.existsSync(evidenceDir)) throw new Error('motion evidence directory already exists');
+  try {
+    const mp4 = path.join(tmp, 'clip.mp4');
+    const width = Math.min(1280, info.width), height = Math.min(720, info.height);
+    ffmpeg(['-ss', String(start), '-i', source, '-t', String(duration), '-map', '0:v:0', '-an', '-sn', '-dn',
+      '-vf', `scale=${width}:${height}:force_original_aspect_ratio=decrease:force_divisible_by=2,fps=30`,
+      '-c:v', 'libx264', '-preset', 'medium', '-crf', '24', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', '-map_metadata', '-1', mp4]);
+    const encoded = probe(mp4);
+    if (!Number.isFinite(encoded.duration) || encoded.duration < 0.25) throw new Error('clip is empty or too short');
+    const durationMs = Math.round(encoded.duration * 1000);
+    const frames = [];
+    const evidenceTmp = path.join(tmp, 'evidence');
+    fs.mkdirSync(evidenceTmp);
+    for (let i = 0; i < 8; i++) {
+      const at = Math.floor(i * Math.max(0, durationMs - 100) / 7);
+      const name = `frame-${i}.webp`;
+      const png = path.join(tmp, 'frame.png');
+      ffmpeg(['-y', '-ss', String(at / 1000), '-i', mp4, '-frames:v', '1', '-vf', 'scale=640:-2', png]);
+      await sharp(png).webp({ quality: 78 }).toFile(path.join(evidenceTmp, name));
+      frames.push({ at_ms: at, image: `motion/${id}/${name}` });
+    }
+    const buffer = fs.readFileSync(mp4);
+    const sha256 = createHash('sha256').update(buffer).digest('hex');
+    const key = `motion/${slug}/${id}-${sha256.slice(0, 16)}.mp4`;
+    const local = localMotionPath(path.join(p.data, '.library', 'media'), key);
+    const clip = {
+      id, title, notes, duration_ms: durationMs, width: encoded.width, height: encoded.height, fps: 30,
+      bytes: buffer.length, sha256, key, poster: frames[0].image, frames,
+      source: { capture, filename: path.basename(source), start_ms: Math.round(start * 1000) },
+    };
+    fs.mkdirSync(path.dirname(evidenceDir), { recursive: true });
+    fs.cpSync(evidenceTmp, evidenceDir, { recursive: true });
+    entry.fm.motion ??= {};
+    entry.fm.motion.clips = [...(entry.fm.motion.clips ?? []), clip];
+    const errors = validateMotion(entry);
+    if (errors.length) throw new Error(errors.join('; '));
+    fs.mkdirSync(path.dirname(local), { recursive: true });
+    fs.copyFileSync(mp4, local);
+    writeEntry(entry);
+    return { slug, clip, local, published: false };
+  } catch (e) {
+    fs.rmSync(evidenceDir, { recursive: true, force: true });
+    throw e;
+  } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+}
+
+export function r2Config(env = process.env) {
+  const required = ['R2_ACCOUNT_ID', 'R2_ACCESS_KEY_ID', 'R2_SECRET_ACCESS_KEY', 'R2_BUCKET', 'R2_PUBLIC_BASE_URL'];
+  const missing = required.filter((k) => !env[k]);
+  if (missing.length) throw new Error(`configure ${missing.join(', ')} locally before publishing`);
+  if (!/^[a-f0-9]{32}$/.test(env.R2_ACCOUNT_ID)) throw new Error('invalid R2_ACCOUNT_ID');
+  if (!isHttpsUrl(env.R2_PUBLIC_BASE_URL)) throw new Error('R2_PUBLIC_BASE_URL must be HTTPS without credentials');
+  const base = new URL(env.R2_PUBLIC_BASE_URL);
+  if (base.search || base.hash) throw new Error('R2_PUBLIC_BASE_URL must not contain a query or fragment');
+  if (base.hostname.endsWith('.r2.dev')) throw new Error('use a production custom domain for R2_PUBLIC_BASE_URL');
+  return { account: env.R2_ACCOUNT_ID, bucket: env.R2_BUCKET, base: base.href.replace(/\/$/, ''),
+    accessKeyId: env.R2_ACCESS_KEY_ID, secretAccessKey: env.R2_SECRET_ACCESS_KEY };
+}
+
+export async function publishMotion({ p = paths(), slug, id, config = r2Config(), upload, fetcher = fetch }) {
+  const entry = entryFor(p, slug);
+  const errors = validateMotion(entry);
+  if (errors.length) throw new Error(errors.join('; '));
+  const clips = (entry.fm.motion?.clips ?? []).filter((c) => !id || c.id === id);
+  if (!clips.length) throw new Error('no matching motion clips');
+  // Preflight the entire selection before uploading anything.
+  const work = clips.map((clip) => {
+    const file = localMotionPath(path.join(p.data, '.library', 'media'), clip.key);
+    const body = fs.readFileSync(file);
+    if (body.length !== clip.bytes || createHash('sha256').update(body).digest('hex') !== clip.sha256)
+      throw new Error(`local video checksum mismatch: ${clip.id}`);
+    return { clip, body, url: `${config.base}/${clip.key}` };
+  });
+  let client;
+  if (!upload) {
+    const { S3Client, PutObjectCommand } = await import('@aws-sdk/client-s3');
+    client = new S3Client({ region: 'auto', endpoint: `https://${config.account}.r2.cloudflarestorage.com`,
+      credentials: { accessKeyId: config.accessKeyId, secretAccessKey: config.secretAccessKey } });
+    upload = (args) => client.send(new PutObjectCommand(args));
+  }
+  try {
+    for (const { clip, body, url } of work) {
+      await upload({ Bucket: config.bucket, Key: clip.key, Body: body, ContentType: 'video/mp4',
+        CacheControl: 'public, max-age=31536000, immutable', Metadata: { sha256: clip.sha256 } });
+      const response = await fetcher(url, { headers: { Range: 'bytes=0-31' }, signal: AbortSignal.timeout(20000) });
+      const type = response.headers.get('content-type')?.split(';')[0];
+      const range = response.headers.get('content-range');
+      if (response.status !== 206 || type !== 'video/mp4' || range !== `bytes 0-31/${clip.bytes}`) {
+        await response.body?.cancel();
+        throw new Error(`uploaded ${clip.id}, but public playback verification failed (HTTP ${response.status}); entry URL was not changed`);
+      }
+      const bytes = Buffer.from(await response.arrayBuffer());
+      if (!bytes.equals(body.subarray(0, 32))) throw new Error(`public video bytes differ for ${clip.id}`);
+    }
+    for (const { clip, url } of work) clip.url = url;
+    writeEntry(entry);
+    return { slug, published: work.map(({ clip, url }) => ({ id: clip.id, url })) };
+  } finally { client?.destroy(); }
+}
+
+export async function run(args = []) {
+  try {
+    const [action, ...rest] = args;
+    const options = {}, positional = [];
+    const allowed = new Set(['slug', 'id', 'title', 'notes', 'capture', 'start', 'duration']);
+    for (let i = 0; i < rest.length; i++) {
+      if (!rest[i].startsWith('--')) { positional.push(rest[i]); continue; }
+      const name = rest[i].slice(2);
+      if (!allowed.has(name) || rest[i + 1] === undefined || rest[i + 1].startsWith('--')) throw new Error(`invalid option ${rest[i]}`);
+      options[name] = rest[++i];
+    }
+    let result;
+    if (action === 'prepare') {
+      if (positional.length !== 1) throw new Error('prepare requires one local video');
+      for (const k of ['capture', 'start', 'duration']) if (options[k] !== undefined) options[k] = Number(options[k]);
+      result = await prepareMotion({ ...options, input: positional[0] });
+    } else if (action === 'publish' && positional.length === 0) result = await publishMotion(options);
+    else throw new Error('usage: library motion prepare <video> --slug <slug> --id <id> --title <title> --notes <notes> [--start 0 --duration 15 --capture 1] | publish --slug <slug> [--id <id>]');
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+  } catch (e) { process.stderr.write(`motion: ${e.message}\n`); return 1; }
+}

package/src/cli/refresh.mjs

@@ -23,6 +23,12 @@ export async function refreshEntry({ slug, transport }) {
   const method = e.fm.captured?.method;
   if (!url) return { refused: `${slug}: refresh needs source.url` };
   if (method === 'frames') return { refused: `${slug}: refresh needs captured.method measured or both, not frames` };
+  // Refresh writes measure.json and the screenshots into the entry ROOT, which is capture 1's
+  // slot. On a multi-capture entry it cannot know that capture 1 is the one source.url
+  // describes — attaching a measured capture flips method to `both` and unlocks this path —
+  // so it would attribute a fresh measurement to a capture that never made it.
+  if ((e.fm.captured?.captures?.length ?? 0) > 1)
+    return { refused: `${slug}: refresh cannot update a multi-capture entry; it does not know which capture's slot it would write` };
   const refusal = await refuseUnsafeUrl(url, { transport });
   if (refusal) return { refused: refusal };
 

package/src/cli/ui.mjs

@@ -7,7 +7,8 @@ function opt(args, name) { const i = args.indexOf(name); return i >= 0 ? args[i
 export async function run(args = []) {
   const p = paths();
   const outDir = path.join(p.data, 'ui');
-  const r = await buildUi({ indexPath: p.index, entriesDir: p.entries, outDir });
+  const previewMediaDir = args.includes('--local-media') ? path.join(p.data, '.library', 'media') : undefined;
+  const r = await buildUi({ indexPath: p.index, entriesDir: p.entries, outDir, previewMediaDir });
   process.stdout.write(`ui: ${r.entries} entries, ${r.drafts} drafts, built into ${outDir}\n`);
   if (args.includes('--serve')) {
     const port = Number(opt(args, '--port') ?? 4180);

package/src/entry.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import yaml from 'js-yaml';
+import { validateMotion } from './motion.mjs';
 import { resolveTerm } from './vocab.mjs';
 
 export const REQUIRED_BLANKS = ['roles', 'feel', 'motion.devices', 'motion.notes', 'type.display', 'type.body', 'body',
@@ -57,7 +58,19 @@ export function validateEntry(entry, vocab) {
       errors.push(`licence gate: tier ported is not allowed with source.kind ${fm.source.kind}`);
     if (blank(fm.ported_from)) errors.push('ported_from: required for tier ported');
   }
-  if (!fs.existsSync(path.join(entry.dir, 'strip.png'))) errors.push('strip.png: missing');
+  // Every strip a capture names, not only the root one: get_entry hands back `strips` built
+  // from these paths, so a capture claiming an artifact it never wrote would otherwise be
+  // reported ok by `check` and then serve a path to a file that is not there.
+  // The same resolution get_entry uses, basename equality and the conventional fallback
+  // included — validating anything else would pass a path the server never serves, or refuse
+  // one it does.
+  const strips = new Set(['strip.webp']);
+  (fm.captured?.captures ?? []).forEach((c, i) => {
+    const named = (c.artifacts ?? []).find((a) => path.basename(String(a)) === 'strip.webp');
+    strips.add(named ?? (i === 0 ? 'strip.webp' : `captures/${i + 1}/strip.webp`));
+  });
+  for (const s of strips) if (!fs.existsSync(path.join(entry.dir, s))) errors.push(`${s}: missing`);
+  errors.push(...validateMotion(entry));
   return { ok: errors.length === 0, errors };
 }
 

package/src/index/build.mjs

@@ -13,6 +13,12 @@ function isoDate(v) {
   return v instanceof Date ? v.toISOString().slice(0, 10) : String(v).slice(0, 10);
 }
 
+function searchableBody(entry) {
+  return [entry.body, entry.fm.motion?.notes,
+    ...(entry.fm.motion?.clips ?? []).map((clip) => `${clip.title}\n${clip.notes}`)]
+    .filter(Boolean).join('\n');
+}
+
 export async function buildIndex({ entriesDir, indexPath, vocab, models }) {
   fs.mkdirSync(path.dirname(indexPath), { recursive: true });
   const tmpPath = indexPath + '.tmp';
@@ -34,7 +40,7 @@ export async function buildIndex({ entriesDir, indexPath, vocab, models }) {
       insEntry.run({ slug: e.slug, title: e.fm.title, tier: e.fm.tier, source_kind: e.fm.source.kind,
         captured_at: isoDate(e.fm.captured.at), dir: e.dir, body: e.body, fm: JSON.stringify(e.fm) });
       for (const [f, t] of tags) insTag.run(e.slug, f, t);
-      insFts.run(e.slug, e.fm.title, e.body, tags.map(([f, t]) => `${f}/${t}`).join(' '));
+      insFts.run(e.slug, e.fm.title, searchableBody(e), tags.map(([f, t]) => `${f}/${t}`).join(' '));
     });
     let n = 0;
     for (const dir of listEntries(entriesDir)) {
@@ -51,9 +57,9 @@ export async function buildIndex({ entriesDir, indexPath, vocab, models }) {
       tx(e, tags);
       if (emb && db.vec) {
         const tagsStr = tags.map(([f, t]) => `${f}/${t}`).join(' ');
-        const tv = await emb.text(e.fm.title + '\n' + e.body + '\n' + tagsStr);
+        const tv = await emb.text(e.fm.title + '\n' + searchableBody(e) + '\n' + tagsStr);
         insVecText.run(e.slug, Buffer.from(tv.buffer));
-        const iv = await emb.image(path.join(e.dir, 'strip.png'));
+        const iv = await emb.image(path.join(e.dir, 'strip.webp'));
         insVecImage.run(e.slug, Buffer.from(iv.buffer));
       }
       n++;

package/src/index/embed.mjs

@@ -32,7 +32,7 @@ export async function getEmbedder({ models, mode = process.env.LIBRARY_EMBED } =
       arm: 'vec', dims: DIMS,
       text: async (s) => stubVec('t:' + s, DIMS.text),
       // ponytail: seeded on byte length + basename, not pixel content. Every
-      // indexed strip shares the basename strip.png, so two strips of the same
+      // indexed strip shares the basename strip.webp, so two strips of the same
       // byte length collide on the same vector — fine for exercising the vec
       // arm offline, not a stand-in for real image similarity.
       image: async (p) => stubVec('i:' + fs.readFileSync(p).length + ':' + path.basename(p), DIMS.image),

package/src/ingest/agreement.mjs

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { observedColours } from './observed.mjs';
+
+// Records numbers, never prose. "canvas declared dark-blue but the frames read warm" is an
+// interpretation, and this library's rule is that the session is the tagger — the server
+// never guesses what a design feels like. Here are the declared values and the observed
+// ones; what the difference means belongs in the body.
+export async function computeAgreement({ fm, dir }) {
+  const captures = fm.captured?.captures ?? [];
+  // Two DISTINCT captures, newest first. A `both` capture satisfies both predicates, so a
+  // plain find() on each side lets one capture stand in as its own frames source — the
+  // attached capture is then ignored while the block is stamped with today's date. The
+  // frames side is resolved first because it is the one actually read: the newest frames
+  // capture is the one an attach just added. One `both` capture on its own therefore
+  // yields null, which is right — there is no second opinion to record.
+  const frames = captures.findLast((c) => c.method === 'frames' || c.method === 'both');
+  const measured = captures.findLast((c) => c !== frames && (c.method === 'measured' || c.method === 'both'));
+  if (!measured || !frames) return null;
+
+  const declared = fm.palette;
+  if (!declared || Object.values(declared).every((v) => !v)) return null;
+
+  const strip = (frames.artifacts ?? []).find((a) => a.endsWith('strip.webp'));
+  if (!strip) return null;
+  const file = path.join(dir, strip);
+  if (!fs.existsSync(file)) return null;
+
+  return {
+    at: new Date().toISOString().slice(0, 10),
+    palette: { declared: { ...declared }, observed: await observedColours(file), from: strip },
+  };
+}

package/src/ingest/attach.mjs

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { parseEntry } from '../entry.mjs';
+import { computeAgreement } from './agreement.mjs';
+
+function isBlank(v) {
+  return v == null || v === '' || (Array.isArray(v) && v.length === 0)
+    || (typeof v === 'object' && Object.values(v).every((x) => x === '' || x == null));
+}
+
+// An entry written before captures[] existed describes one capture in its top-level fields.
+// Synthesise it rather than dropping it, so attaching to an old entry does not lose what it
+// already recorded.
+function existingCaptureFrom(fm) {
+  const c = { method: fm.captured.method, input: fm.source?.url ?? null, artifacts: ['strip.webp'] };
+  if (fm.captured.method !== 'frames') c.artifacts.push('measure.json', 'screen-1440.png', 'screen-390.png');
+  if (fm.media?.frames) c.frames = fm.media.frames;
+  if (fm.media?.duration_ms) c.duration_ms = fm.media.duration_ms;
+  return c;
+}
+
+// `both` keeps its existing meaning — measured AND frames are present — which is what
+// refresh.mjs is really asking when it says "needs measured or both, not frames": is there
+// a URL here I can re-measure.
+function summaryMethod(captures) {
+  const measured = captures.some((c) => c.method === 'measured' || c.method === 'both');
+  const frames = captures.some((c) => c.method === 'frames' || c.method === 'both');
+  if (measured && frames) return 'both';
+  return measured ? 'measured' : 'frames';
+}
+
+export async function attachCapture({ entriesDir, slug, capture, palette, type, media, sourceUrl, tool }) {
+  const dir = path.join(entriesDir, slug);
+  const e = parseEntry(dir);
+  const fm = e.fm;
+
+  // An EMPTY captures[] is treated like an absent one: the entry still describes a capture in
+  // its top-level fields, and nextCaptureIndex counts it as capture 1, so synthesising it here
+  // is what keeps the list and the captures/<n>/ paths agreeing.
+  const captures = fm.captured.captures?.length ? fm.captured.captures : [existingCaptureFrom(fm)];
+  captures.push(capture);
+
+  // Fill only if blank. palette and type are mechanically derived, but the session may have
+  // corrected them, and an attach must never overwrite a decision it did not make.
+  if (palette && isBlank(fm.palette)) fm.palette = palette;
+  if (type && isBlank(fm.type)) fm.type = type;
+  if (media && isBlank(fm.media)) fm.media = media;
+  // Same rule for source.url: an entry ingested from a local file has none, and without this
+  // a measured capture attached to it leaves refresh refusing "needs source.url" forever.
+  if (sourceUrl && isBlank(fm.source?.url)) fm.source = { ...fm.source, url: sourceUrl };
+
+  fm.captured = {
+    ...fm.captured,
+    method: summaryMethod(captures),
+    at: new Date().toISOString().slice(0, 10),
+    tool: tool ?? fm.captured.tool,
+    captures,
+  };
+
+  const agreement = await computeAgreement({ fm, dir });
+  if (agreement) fm.agreement = agreement;
+
+  const body = e.body ? `\n${e.body}\n` : '';
+  fs.writeFileSync(path.join(dir, 'entry.md'), `---\n${yaml.dump(fm, { lineWidth: 120 })}---\n${body}`);
+  return { dir, captures, method: fm.captured.method };
+}

package/src/ingest/draft.mjs

@@ -10,13 +10,16 @@ function isBlank(v) {
   return v == null || v === '' || (Array.isArray(v) && v.length === 0);
 }
 
-export function writeDraft({ entriesDir, slug, title, source, media, captured, palette, type }) {
+export function writeDraft({ entriesDir, slug, title, source, media, captured, palette, type, captures }) {
   const dir = path.join(entriesDir, slug);
   fs.mkdirSync(dir, { recursive: true });
   const fm = {
     slug, title, tier: 'inspiration',
     source: { kind: source.kind, url: source.url ?? null, license: source.license },
-    captured, media,
+    // captures[] is additive: an entry without it means a single capture, so every entry
+    // written before this change stays valid and nothing migrates.
+    captured: captures ? { ...captured, captures } : captured,
+    media,
     roles: [], feel: [],
     palette: palette ?? { canvas: '', ink: '', accent: '' },
     type: type ?? { display: '', body: '' },

package/src/ingest/frames.mjs

@@ -59,20 +59,34 @@ async function videoFrames(input, want) {
   }
 }
 
-export async function compositeStrip(tiles, w, h, outPng) {
+// A strip is a contact sheet, and these ship inside the npm package: a six-column sheet of
+// 1440-wide frames is 9600x6000, ~50 MB as PNG, and 56 of them made the tarball too large for
+// npm to build at all. 2400px leaves ~400px per frame, which keeps a headline and a nav
+// readable; 1800 does not. The single write point for every strip in the library.
+const STRIP_WIDTH = 2400, STRIP_QUALITY = 80;
+export function writeStrip(pipeline, out) {
+  return pipeline.resize({ width: STRIP_WIDTH, withoutEnlargement: true }).webp({ quality: STRIP_QUALITY }).toFile(out);
+}
+
+export async function compositeStrip(tiles, w, h, out) {
   const cols = tiles.length > 12 ? 6 : Math.min(3, tiles.length), rows = Math.ceil(tiles.length / cols);
-  await sharp({ create: { width: w * cols, height: h * rows, channels: 3, background: '#000' } })
+  // Composited to a buffer at grid size and only then handed to writeStrip. sharp applies
+  // resize BEFORE composite whatever order they are called in, so resizing the same pipeline
+  // would lay unscaled tiles onto a shrunken canvas — clipping the last column, or refusing
+  // outright once a tile is taller than the resized sheet.
+  const grid = await sharp({ create: { width: w * cols, height: h * rows, channels: 3, background: '#000' } })
     .composite(tiles.map((b, k) => ({ input: b, left: (k % cols) * w, top: Math.floor(k / cols) * h })))
-    .png().toFile(outPng);
+    .png().toBuffer();
+  await writeStrip(sharp(grid), out);
 }
 
-export async function sampleFrames(input, outPng, { frames: want } = {}) {
+export async function sampleFrames(input, out, { frames: want } = {}) {
   if (VIDEO.test(input)) {
     const { files, durationMs, cleanup } = await videoFrames(input, want);
     try {
       const tiles = await Promise.all(files.map((f) => sharp(f).png().toBuffer()));
       const first = await sharp(files[0]).metadata();
-      await compositeStrip(tiles, first.width, first.height, outPng);
+      await compositeStrip(tiles, first.width, first.height, out);
       return { frames: files.length, durationMs, sampled: files.map((_, i) => i) };
     } finally {
       cleanup();
@@ -88,6 +102,6 @@ export async function sampleFrames(input, outPng, { frames: want } = {}) {
   const sampled = n >= frames ? [...Array(frames).keys()] : [...Array(n).keys()].map((i) => Math.round((i * (frames - 1)) / (n - 1)));
   const w = meta.width, h = meta.pageHeight ?? meta.height;
   const tiles = await Promise.all(sampled.map((i) => sharp(input, { page: i }).png().toBuffer()));
-  await compositeStrip(tiles, w, h, outPng);
+  await compositeStrip(tiles, w, h, out);
   return { frames, durationMs, sampled };
 }

package/src/ingest/measure.mjs

@@ -1,9 +1,34 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import sharp from 'sharp';
 
 const VIEWPORT_WIDE = { width: 1440, height: 900 };
 const VIEWPORT_NARROW = { width: 390, height: 844 };
 
+export function captureFailure({ status, title = '', bodyText = '' }) {
+  if ([401, 403, 429, 451].includes(status)) return `page refused capture (HTTP ${status})`;
+  if (status >= 400) return `page returned HTTP ${status}`;
+  const text = `${title}\n${bodyText}`.replace(/\s+/g, ' ').toLowerCase();
+  if (/sorry,? you have been blocked|unable to access|attention required|cf-ray|access denied/.test(text))
+    return 'page refused capture (block page detected)';
+  // A loaded document with no readable page content is normally a still-hydrating
+  // application or a challenge screen. Do not preserve its spinner as a reference.
+  if (bodyText.replace(/\s+/g, '').length < 40) return 'page did not render meaningful content';
+  return null;
+}
+
+async function blankScreenshotReason(file) {
+  const { data } = await sharp(file).resize(48, 30, { fit: 'fill' }).removeAlpha().raw().toBuffer({ resolveWithObject: true });
+  const colours = new Set();
+  const counts = new Map();
+  for (let i = 0; i < data.length; i += 3) {
+    const key = `${data[i] >> 4},${data[i + 1] >> 4},${data[i + 2] >> 4}`;
+    colours.add(key); counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  const dominant = Math.max(...counts.values()) / (data.length / 3);
+  return colours.size <= 2 || dominant >= 0.995 ? 'page screenshot did not render meaningful content' : null;
+}
+
 // Runs inside the page via page.evaluate — no Node globals, no sharp, nothing
 // from this module's closure crosses the Playwright boundary.
 function collect() {
@@ -111,7 +136,13 @@ export async function measure(url, outDir, { chrome = process.env.CHROME_PATH, r
     const page = await browser.newPage();
     await page.setViewportSize(VIEWPORT_WIDE);
     try {
-      await page.goto(url, { waitUntil: 'load', timeout: 45000 });
+      const response = await page.goto(url, { waitUntil: 'load', timeout: 45000 });
+      // Let client-rendered pages complete their initial hydration before judging
+      // the document or writing any image artifact.
+      await page.waitForTimeout(1000);
+      const diagnostic = await page.evaluate(() => ({ title: document.title, bodyText: document.body?.innerText || '' }));
+      const failure = captureFailure({ status: response?.status(), ...diagnostic });
+      if (failure) return { ok: false, error: failure };
     } catch (err) {
       return { ok: false, error: `page failed to load: ${err.message}` };
     }
@@ -119,6 +150,8 @@ export async function measure(url, outDir, { chrome = process.env.CHROME_PATH, r
     fs.mkdirSync(outDir, { recursive: true });
     const shot1440 = path.join(outDir, 'screen-1440.png');
     await page.screenshot({ path: shot1440, fullPage: false });
+    const blankShot = await blankScreenshotReason(shot1440);
+    if (blankShot) return { ok: false, error: blankShot };
     screenshots[1440] = shot1440;
 
     if (record) {

package/src/ingest/observed.mjs

@@ -0,0 +1,29 @@
+import sharp from 'sharp';
+
+// Dominant colours as a pixel-frequency histogram, NOT a perceptual palette. A strip is
+// frames stitched together, so a colour filling most of the running time dominates whether
+// or not a viewer would call it the palette — that ceiling is recorded in the README.
+//
+// Four bits per channel keeps near-identical shades in one bucket. Resizing to 32x32 makes
+// the cost constant regardless of how long the strip is, and interpolates at band edges,
+// which is why this returns the top N rather than the whole histogram.
+export async function observedColours(imagePath, { top = 3 } = {}) {
+  const { data, info } = await sharp(imagePath)
+    .resize(32, 32, { fit: 'fill' })
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+
+  const counts = new Map();
+  for (let i = 0; i < data.length; i += info.channels) {
+    const key = ((data[i] >> 4) << 8) | ((data[i + 1] >> 4) << 4) | (data[i + 2] >> 4);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+
+  return [...counts.entries()]
+    // Count descending, then key ascending: without the tie-break, two colours with equal
+    // pixel counts would order by Map insertion and the result would not be reproducible.
+    .sort((a, b) => b[1] - a[1] || a[0] - b[0])
+    .slice(0, top)
+    .map(([key]) => '#' + [(key >> 8) & 15, (key >> 4) & 15, key & 15]
+      .map((v) => (v * 17).toString(16).padStart(2, '0')).join(''));
+}

package/src/mcp/http.mjs

@@ -44,7 +44,7 @@ async function handle(req, res, p, token, embedder) {
   }
   // req.url, not url.pathname: WHATWG URL parsing already folds `%2e%2e`/`..` before
   // serveFile's own prefix check would ever see them (see src/ui/serve.mjs).
-  return serveFile(path.join(p.data, 'ui'), req.url, res);
+  return serveFile(path.join(p.data, 'ui'), req.url, res, req);
 }
 
 export async function serveHttp() {

package/src/mcp/instructions.mjs

@@ -14,4 +14,5 @@ Where the project's own conventions and this library disagree, the project wins.
 
 BUDGET: a tool result is re-read on every later turn, so a study costs the transcript, not the call. One recommend, or one search per role you actually need, then get_entry on the three to five you keep, is a complete study. A further search costs more than it finds. Use get_entry with detail:"summary" to decide, detail:"full" only to build.
 
-READING A HIT: ranks.fts null means it matched by semantic distance alone, with no keyword in common. A role whose hits are all weak has no reference — report that rather than filling it with a weak one.`;
+READING A HIT: ranks.fts null means it matched by semantic distance alone, with no keyword in common. A role whose hits are all weak has no reference — report that rather than filling it with a weak one.
+Use get_motion for timestamped images and optional video URLs when studying motion.`;

package/src/mcp/prompts.mjs

@@ -16,7 +16,7 @@ export function addEntryPrompt(ctx, a) {
 Arguments given:
 ${given || '- (none)'}
 
-The server does the mechanical half: it samples frames into \`strip.png\` and writes a
+The server does the mechanical half: it samples frames into \`strip.webp\` and writes a
 draft with the judgement fields blank. **The session is the tagger.** Nothing in the
 server guesses what a design feels like, and a draft is never saved with a guess the
 session did not make.
@@ -56,6 +56,17 @@ session did not make.
    --title "content: <title>" --body "<one line: source kind and licence>"\`. No attribution
    lines in the commit. The hosted instance picks the entry up on the redeploy after merge.
 
+## When the draft holds more than one capture
+
+\`captured.captures\` lists every capture on this entry. Open the strip of **each** one, not
+only the first — a second source exists because it shows something the first cannot, and
+reading one of two is worse than reading one, because it looks complete.
+
+The body then carries a \`## Sources\` section: one line per capture naming what it
+contributed, and one line for each place they disagree, saying which source you trusted and
+why. If an \`agreement\` block is present the server has already recorded the declared and
+observed colours; it makes no claim about which is right, and saying so is your job.
+
 ## Tagging rubric
 
 Read the whole page before tagging any section: roster first, then feel, then motion.

package/src/mcp/resources.mjs

@@ -1,8 +1,22 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { parseEntry } from '../entry.mjs';
+import { motionFrame } from '../motion.mjs';
 
 export function registerResources(server, ctx) {
+  server.registerResource(
+    'motion-frame',
+    new ResourceTemplate('library://motion/{slug}/{clip}/{frame}', { list: undefined }),
+    { title: 'Motion frame', description: 'One timestamped WebP frame from a motion clip.', mimeType: 'image/webp' },
+    async (uri, { slug, clip, frame }) => {
+      if (!/^[a-z0-9-]+$/.test(slug) || !/^[a-z0-9-]+$/.test(clip) || !/^(?:[0-9]|1[01])$/.test(frame))
+        throw new Error('invalid motion frame');
+      const entry = parseEntry(path.join(ctx.paths.entries, slug));
+      const image = motionFrame(entry, clip, Number(frame));
+      return { contents: [{ uri: uri.href, mimeType: 'image/webp', blob: image.data }] };
+    },
+  );
   server.registerResource(
     'vocab',
     'library://vocab',