@yojahny/wp-design-library 0.3.0 → 0.5.1

package/src/mcp/tools.mjs

@@ -4,6 +4,8 @@ import { z } from 'zod';
 import { openIndex, search, getEntry, similar } from '../index/query.mjs';
 import { resolveTerm } from '../vocab.mjs';
 import { refuseUnsafeUrl } from '../ingest/url-guard.mjs';
+import { getMotion, motionFrame } from '../motion.mjs';
+import { parseEntry } from '../entry.mjs';
 
 const facetList = z.array(z.string()).optional();
 const FILTER_FACETS = ['role', 'feel', 'motion', 'source'];
@@ -76,7 +78,7 @@ export function makeTools(ctx) {
     },
     {
       name: 'get_entry',
-      description: "Return one entry: frontmatter, prose body, and the path to its strip.png. detail:'summary' returns the body's first paragraph instead of the whole body — enough to decide whether to fetch the rest.",
+      description: "Return one entry: frontmatter, prose body, and the path to its strip.webp. detail:'summary' returns the body's first paragraph instead of the whole body — enough to decide whether to fetch the rest.",
       schema: z.object({
         slug: z.string(),
         detail: z.enum(['summary', 'full']).default('full'),
@@ -84,7 +86,22 @@ export function makeTools(ctx) {
       handler: withDb((db, { slug, detail }) => {
         const e = getEntry(db, slug);
         if (!e) return { refused: `no entry with slug ${slug}` };
-        const out = { ...e, strip: `${e.dir}/strip.png` };
+        // Every capture's strip, one slot per capture, capture 1 first — strips[i] always
+        // describes captures[i]. `strip` is derived from e.dir alone, independently of what
+        // a capture's own artifacts happen to list, so a capture that names no strip falls
+        // back to its conventional path (entry root for capture 1, captures/<n>/strip.webp
+        // after) instead of being silently dropped: that keeps strips[0] === strip true by
+        // construction, not by writer discipline. Match on basename exactly, not by suffix —
+        // a suffix match would let an unrelated file like extra-strip.webp count as a strip.
+        const captures = e.fm?.captured?.captures ?? [];
+        const conventionalStrip = (i) => (i === 0 ? 'strip.webp' : `captures/${i + 1}/strip.webp`);
+        const strips = captures.length
+          ? captures.map((c, i) => {
+              const named = (c.artifacts ?? []).find((a) => path.basename(a) === 'strip.webp');
+              return `${e.dir}/${named ?? conventionalStrip(i)}`;
+            })
+          : [`${e.dir}/strip.webp`];
+        const out = { ...e, strip: `${e.dir}/strip.webp`, strips };
         if (detail !== 'summary') return out;
         // The first PROSE paragraph. Bodies conventionally open with `## What it does`,
         // so splitting on the first blank line alone would return a bare heading, which
@@ -100,9 +117,34 @@ export function makeTools(ctx) {
         return { ...out, body: first.trim(), detail: 'summary' };
       }),
     },
+    {
+      name: 'get_motion',
+      description: 'Inspect one motion clip at original playback speed. Returns video URL when published, provenance, observed motion notes, and timestamped frames as native images by default. Use clip to select from available clips; timestamps are relative to the clip. A video URL alone does not provide video understanding.',
+      schema: z.object({
+        slug: z.string().regex(/^[a-z0-9-]+$/),
+        clip: z.string().regex(/^[a-z0-9-]+$/).optional(),
+        include_frames: z.boolean().default(true),
+      }),
+      handler: async ({ slug, clip, include_frames }) => {
+        const dir = path.join(ctx.paths.entries, slug);
+        if (!fs.existsSync(path.join(dir, 'entry.md'))) return { refused: `no entry with slug ${slug}` };
+        return { ...getMotion(parseEntry(dir), clip), frames_included: include_frames };
+      },
+      content: (out) => {
+        if (out.refused || !out.frames_included) return [];
+        const entry = parseEntry(path.join(ctx.paths.entries, out.slug));
+        return out.clip.frames.flatMap((_, i) => {
+          const frame = motionFrame(entry, out.clip.id, i);
+          return [
+            { type: 'text', text: `Frame ${i}: ${(frame.at_ms / 1000).toFixed(3)} seconds into ${out.clip.id}` },
+            { type: 'image', mimeType: 'image/webp', data: frame.data },
+          ];
+        });
+      },
+    },
     {
       name: 'similar',
-      description: "Find entries visually similar to a slug's strip.png, or to an image file, by vector distance on vec_image. Exactly one of slug/image is required.",
+      description: "Find entries visually similar to a slug's strip.webp, or to an image file, by vector distance on vec_image. Exactly one of slug/image is required.",
       schema: z.object({
         slug: z.string().optional(),
         image: z.string().optional(),
@@ -161,13 +203,14 @@ export function makeTools(ctx) {
     },
     {
       name: 'add',
-      description: 'Ingest a video/animated image, or measure a live https:// URL with the system Chrome: sample frames or measure into strip.png/measure.json and write a draft entry. Returns the blank fields the caller must fill before save_entry.',
+      description: 'Ingest a video/animated image, or measure a live https:// URL with the system Chrome: sample frames or measure into strip.webp/measure.json and write a draft entry. Returns the blank fields the caller must fill before save_entry. Pass attach to add a second capture of the same site — a video beside a live URL — instead of refusing; the existing entry\'s tags, body, palette and type are left untouched.',
       schema: z.object({
         input: z.string(), slug: z.string().regex(/^[a-z0-9-]+$/), title: z.string().min(1),
         source: z.object({ kind: z.enum(['own', 'open', 'paid', 'public-site']), url: z.string().url().optional(), license: z.string().min(1) }),
         force: z.boolean().default(false),
         frames: z.number().int().min(6).max(36).optional(),
         record: z.boolean().default(false),
+        attach: z.boolean().default(false),
       }),
       handler: async (a) => {
         // A URL is fetched over the network by Chrome, not read off disk on the
@@ -205,7 +248,7 @@ export function registerTools(server, tools) {
   for (const t of tools) {
     server.registerTool(t.name, { description: t.description, inputSchema: t.schema.shape }, async (args) => {
       const out = await t.handler(args);
-      return { content: [{ type: 'text', text: JSON.stringify(out) }], structuredContent: out };
+      return { content: [{ type: 'text', text: JSON.stringify(out) }, ...(t.content?.(out) ?? [])], structuredContent: out };
     });
   }
 }

package/src/motion.mjs

@@ -0,0 +1,94 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const KEY = /^motion\/[a-z0-9-]+\/[a-z0-9-]+-[a-f0-9]{16}\.mp4$/;
+const MAX_IMAGE_BYTES = 512 * 1024;
+
+export function isHttpsUrl(value) {
+  try {
+    const u = new URL(value);
+    return u.protocol === 'https:' && !u.username && !u.password;
+  } catch { return false; }
+}
+
+// Only generated WebP evidence inside this entry is readable by the MCP server.
+// realpath prevents a symlink in an otherwise safe-looking path escaping the entry.
+export function motionImagePath(dir, relative) {
+  if (typeof relative !== 'string' || !/^motion\/[a-z0-9-]+\/[a-z0-9-]+\.webp$/.test(relative))
+    throw new Error('invalid motion image path');
+  const root = fs.realpathSync(dir);
+  const file = fs.realpathSync(path.join(root, relative));
+  if (!file.startsWith(root + path.sep)) throw new Error('motion image escapes entry');
+  const stat = fs.statSync(file);
+  if (!stat.isFile() || stat.size > MAX_IMAGE_BYTES) throw new Error('motion image missing or too large');
+  return file;
+}
+
+export function localMotionPath(mediaDir, key) {
+  if (!KEY.test(key)) throw new Error('invalid motion object key');
+  return path.join(mediaDir, key);
+}
+
+export function validateMotion(entry) {
+  const clips = entry.fm.motion?.clips;
+  if (clips === undefined) return [];
+  if (!Array.isArray(clips) || clips.length > 12) return ['motion.clips: expected at most 12 clips'];
+  const errors = [], seen = new Set();
+  for (const [i, c] of clips.entries()) {
+    const prefix = `motion.clips[${i}]`;
+    if (!c || typeof c !== 'object') { errors.push(`${prefix}: expected a clip`); continue; }
+    const fail = (s) => errors.push(`${prefix}.${s}`);
+    if (typeof c.id !== 'string' || !ID.test(c.id) || seen.has(c.id)) fail('id: invalid or duplicate');
+    seen.add(c.id);
+    for (const field of ['title', 'notes'])
+      if (typeof c[field] !== 'string' || !c[field].trim()) fail(`${field}: required`);
+    if (!Number.isInteger(c.duration_ms) || c.duration_ms <= 0 || c.duration_ms > 15050) fail('duration_ms: expected up to 15 seconds');
+    if (!Number.isInteger(c.width) || c.width <= 0 || c.width > 1280) fail('width: expected up to 1280');
+    if (!Number.isInteger(c.height) || c.height <= 0 || c.height > 720) fail('height: expected up to 720');
+    if (!Number.isFinite(c.fps) || c.fps <= 0 || c.fps > 30) fail('fps: expected up to 30');
+    if (!Number.isInteger(c.bytes) || c.bytes <= 0) fail('bytes: required');
+    if (!/^[a-f0-9]{64}$/.test(c.sha256)) fail('sha256: required');
+    if (!KEY.test(c.key) || c.key !== `motion/${path.basename(entry.dir)}/${c.id}-${String(c.sha256).slice(0, 16)}.mp4`) fail('key: invalid');
+    if (c.url !== undefined && !isHttpsUrl(c.url)) fail('url: expected HTTPS without credentials');
+    if (!Number.isInteger(c.source?.capture) || c.source.capture < 1 || c.source.capture > (entry.fm.captured?.captures?.length ?? 1)) fail('source.capture: unknown capture');
+    if (!Number.isInteger(c.source?.start_ms) || c.source.start_ms < 0) fail('source.start_ms: invalid');
+    if (typeof c.source?.filename !== 'string' || !c.source.filename.trim() || /[/\\]/.test(c.source.filename)) fail('source.filename: expected basename');
+    const checkImage = (image) => {
+      try { motionImagePath(entry.dir, image); } catch (e) { fail(`image: ${e.message}`); }
+    };
+    checkImage(c.poster);
+    if (!Array.isArray(c.frames) || c.frames.length < 2 || c.frames.length > 12) { fail('frames: expected 2–12 timestamped frames'); continue; }
+    let previous = -1;
+    for (const f of c.frames) {
+      if (!Number.isInteger(f?.at_ms) || f.at_ms <= previous || f.at_ms >= c.duration_ms) fail('frames: timestamps must increase within the clip');
+      previous = f?.at_ms;
+      checkImage(f?.image);
+    }
+  }
+  return errors;
+}
+
+export function getMotion(entry, id) {
+  const errors = validateMotion(entry);
+  if (errors.length) return { refused: errors.join('; ') };
+  const clips = entry.fm.motion?.clips ?? [];
+  const clip = id ? clips.find((c) => c.id === id) : clips[0];
+  if (!clip) return { refused: id ? `no motion clip ${id}` : 'no motion clips for this entry' };
+  const slug = path.basename(entry.dir);
+  return {
+    slug, available: clips.map(({ id, title }) => ({ id, title })),
+    clip: { ...clip, frames: clip.frames.map((f, i) => ({
+      ...f, resource_uri: `library://motion/${slug}/${clip.id}/${i}`,
+    })) },
+    timing: 'Timestamps are relative to this clip. Playback is at original speed; motion notes are observed, not instrumented measurements.',
+  };
+}
+
+export function motionFrame(entry, clipId, frameIndex) {
+  const result = getMotion(entry, clipId);
+  if (result.refused) throw new Error(result.refused);
+  const frame = result.clip.frames[frameIndex];
+  if (!frame) throw new Error('no motion frame');
+  return { at_ms: frame.at_ms, data: fs.readFileSync(motionImagePath(entry.dir, frame.image)).toString('base64') };
+}

package/src/ui/build.mjs

@@ -1,8 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import sharp from 'sharp';
 import { listEntries, parseEntry, validateEntry } from '../entry.mjs';
 import { loadVocab, FACETS } from '../vocab.mjs';
+import { validateMotion, motionImagePath, localMotionPath } from '../motion.mjs';
 
 const DIR = path.dirname(fileURLToPath(import.meta.url));
 const TPL = path.join(DIR, 'templates');
@@ -43,7 +45,7 @@ function filterFieldset(facet, terms) {
 }
 
 function card(row) {
-  const img = row.strip ? `<img src="${row.strip}" alt="">` : `<div class="ph"></div>`;
+  const img = row.thumbnail ? `<img src="${row.thumbnail}" alt="" loading="lazy" decoding="async">` : `<div class="ph"></div>`;
   const badge = row.draft ? ' <span class="badge">draft</span>' : '';
   const tags = esc([...row.roles, ...row.feel, ...row.motion].join(', '));
   const data = `data-role="${esc(row.roles.join(' '))}" data-feel="${esc(row.feel.join(' '))}" data-motion="${esc(row.motion.join(' '))}"`;
@@ -61,7 +63,68 @@ function measurementsHtml(dir) {
     `<p>${(m.sections ?? []).length} sections measured.</p>`;
 }
 
-function writeEntryPage(outDir, entry, row) {
+// source.url and capture.input come out of an entry file — data this server did not write.
+// esc() stops attribute breakout but not a `javascript:` or `data:` scheme in an href, and
+// this is the first data-driven href in the template. Parse with URL and check protocol
+// rather than matching a prefix, because URL normalises the cases a prefix check misses.
+function isWebUrl(s) {
+  try { return ['http:', 'https:'].includes(new URL(s).protocol); } catch { return false; }
+}
+
+function linkify(value) {
+  const s = String(value ?? '').trim();
+  if (!s) return '';
+  return isWebUrl(s) ? `<a href="${esc(s)}" rel="noreferrer">${esc(s)}</a>` : esc(s);
+}
+
+// Named fieldRow, not row: writeEntryPage's third parameter is already called `row` (the
+// gallery row object), and that parameter would shadow a module-level `row` for the whole
+// function body — silently turning `row('Site', ...)` into a call on a plain object.
+function fieldRow(label, html) {
+  return html ? `<dt>${esc(label)}</dt><dd>${html}</dd>` : '';
+}
+
+// A local capture shows its basename only: an absolute path on the ingesting machine is
+// neither useful to a reader nor something to publish. A capture input is entry-file data
+// exactly like source.url, so it goes through the same protocol guard — not a second,
+// looser one. A prefix match would also miss `HTTPS://…`, which URL normalises.
+function captureLabel(input) {
+  const s = String(input ?? '').trim();
+  if (!s) return '';
+  return isWebUrl(s) ? linkify(s) : esc(s.split('/').pop());
+}
+
+function motionHtml(outDir, entry, previewMediaDir) {
+  const clips = entry.fm.motion?.clips ?? [];
+  if (!clips.length || validateMotion(entry).length) return '';
+  const slug = path.basename(entry.dir);
+  const figures = clips.map((clip) => {
+    const targetDir = path.join(outDir, 'motion', slug, clip.id);
+    fs.mkdirSync(targetDir, { recursive: true });
+    const imageUrl = (relative) => {
+      const name = path.basename(relative);
+      fs.copyFileSync(motionImagePath(entry.dir, relative), path.join(targetDir, name));
+      return `../motion/${slug}/${clip.id}/${name}`;
+    };
+    const poster = imageUrl(clip.poster);
+    let video = clip.url;
+    if (!video && previewMediaDir) {
+      const local = localMotionPath(previewMediaDir, clip.key);
+      if (fs.existsSync(local)) {
+        fs.copyFileSync(local, path.join(targetDir, 'clip.mp4'));
+        video = `../motion/${slug}/${clip.id}/clip.mp4`;
+      }
+    }
+    const player = video
+      ? `<video controls playsinline preload="none" poster="${esc(poster)}" width="${clip.width}" height="${clip.height}" aria-label="${esc(clip.title)}"><source src="${esc(video)}" type="video/mp4"></video>`
+      : `<img src="${esc(poster)}" alt="${esc(clip.title)}" loading="lazy" decoding="async">`;
+    const frames = clip.frames.map((frame) => `<figure><img src="${esc(imageUrl(frame.image))}" alt="${esc(clip.title)} at ${(frame.at_ms / 1000).toFixed(2)} seconds" loading="lazy" decoding="async"><figcaption>${(frame.at_ms / 1000).toFixed(2)}s</figcaption></figure>`).join('');
+    return `<section class="motion-clip"><h3>${esc(clip.title)}</h3>${player}<p>${esc(clip.notes)}</p><p>${(clip.duration_ms / 1000).toFixed(1)} seconds · Original speed</p><details><summary>Timestamped frames</summary><div class="motion-frames">${frames}</div></details></section>`;
+  });
+  return `<section aria-label="Motion previews"><h2>Motion previews</h2>${figures.join('\n')}</section>`;
+}
+
+function writeEntryPage(outDir, entry, row, previewMediaDir) {
   const tpl = fs.readFileSync(path.join(TPL, 'entry.html'), 'utf8');
   const html = render(tpl, {
     TITLE: esc(row.title), TIER: esc(row.tier), ROLES: esc(row.roles.join(', ')), FEEL: esc(row.feel.join(', ')),
@@ -69,6 +132,10 @@ function writeEntryPage(outDir, entry, row) {
     CAPTURED: esc(row.captured), STRIP_IMG: row.strip ? `<img src="../${row.strip}" alt="">` : '',
     DRAFT_BADGE: row.draft ? '<span class="badge">draft</span>' : '', BODY: mdToHtml(entry.body),
     MEASUREMENTS: measurementsHtml(entry.dir),
+    MOTION_CLIPS: motionHtml(outDir, entry, previewMediaDir),
+    SITE_ROW: fieldRow('Site', linkify(entry.fm.source?.url)),
+    CAPTURES_ROW: fieldRow('Captures', (entry.fm.captured?.captures ?? [])
+      .map((c) => `${esc(c.method)}: ${captureLabel(c.input)}`).join('<br>')),
   });
   fs.writeFileSync(path.join(outDir, 'entry', `${row.slug}.html`), html);
 }
@@ -76,12 +143,13 @@ function writeEntryPage(outDir, entry, row) {
 // `indexPath` is accepted for interface symmetry with buildIndex but unused: a draft is an
 // entry that fails validateEntry, and buildIndex never puts a failing entry in the sqlite
 // index — so entries/ is the one place both valid and draft entries can be read from.
-export async function buildUi({ indexPath, entriesDir, outDir }) {
+export async function buildUi({ indexPath, entriesDir, outDir, previewMediaDir }) {
   void indexPath;
   const vocab = loadVocab();
   fs.rmSync(outDir, { recursive: true, force: true });
   fs.mkdirSync(path.join(outDir, 'entry'), { recursive: true });
   fs.mkdirSync(path.join(outDir, 'strips'), { recursive: true });
+  fs.mkdirSync(path.join(outDir, 'thumbnails'), { recursive: true });
 
   const rows = [];
   for (const dir of listEntries(entriesDir)) {
@@ -93,9 +161,15 @@ export async function buildUi({ indexPath, entriesDir, outDir }) {
     // slug === dir name, so fm.slug can carry path-traversal or markup and must never
     // reach a path or an unescaped attribute.
     const slug = path.basename(dir);
-    const stripSrc = path.join(dir, 'strip.png');
+    const stripSrc = path.join(dir, 'strip.webp');
     const hasStrip = fs.existsSync(stripSrc);
-    if (hasStrip) fs.copyFileSync(stripSrc, path.join(outDir, 'strips', `${slug}.png`));
+    if (hasStrip) {
+      fs.copyFileSync(stripSrc, path.join(outDir, 'strips', `${slug}.webp`));
+      // The index is a browsing surface. Its previews must not make each visitor
+      // download a multi-frame source sheet; the full strip remains on the detail page.
+      await sharp(stripSrc).resize(640, 480, { fit: 'cover', position: 'north' })
+        .webp({ quality: 72, effort: 4 }).toFile(path.join(outDir, 'thumbnails', `${slug}.webp`));
+    }
     const fm = entry.fm;
     const capturedAt = fm.captured?.at;
     const captured = capturedAt instanceof Date ? capturedAt.toISOString().slice(0, 10) : String(capturedAt ?? '');
@@ -104,10 +178,12 @@ export async function buildUi({ indexPath, entriesDir, outDir }) {
     const row = {
       slug, title: fm.title || fm.slug || slug, tier: fm.tier || '', roles: fm.roles ?? [], feel: fm.feel ?? [],
       motion: fm.motion?.devices ?? [], source: fm.source?.kind || '', captured,
-      strip: hasStrip ? `strips/${slug}.png` : null, draft: !ok,
+      strip: hasStrip ? `strips/${slug}.webp` : null,
+      thumbnail: hasStrip ? `thumbnails/${slug}.webp` : null,
+      draft: !ok,
     };
     rows.push(row);
-    writeEntryPage(outDir, entry, row);
+    writeEntryPage(outDir, entry, row, previewMediaDir);
   }
   rows.sort((a, b) => b.captured.localeCompare(a.captured));
 

package/src/ui/serve.mjs

@@ -7,6 +7,8 @@ const MIME = {
   '.js': 'text/javascript; charset=utf-8',
   '.json': 'application/json; charset=utf-8',
   '.png': 'image/png',
+  '.webp': 'image/webp',
+  '.mp4': 'video/mp4',
 };
 
 // Serves one file under `root`. Takes the raw request-target (`req.url`, or the
@@ -14,7 +16,7 @@ const MIME = {
 // `%2e%2e` and `..` to the same normalized path *before* any code here runs, which
 // would make a prefix check look load-bearing while actually never seeing a path
 // that leaves `root`. Decoding and joining ourselves is what actually blocks it.
-export function serveFile(root, rawPath, res) {
+export function serveFile(root, rawPath, res, req = {}) {
   const pathname = rawPath.split('?')[0];
   let rel;
   try { rel = decodeURIComponent(pathname); } catch { res.writeHead(404); return res.end(); }
@@ -22,15 +24,38 @@ export function serveFile(root, rawPath, res) {
   const file = path.join(root, rel);
   if (file !== root && !file.startsWith(root + path.sep)) { res.writeHead(404); return res.end(); }
   if (!fs.existsSync(file) || fs.statSync(file).isDirectory()) { res.writeHead(404); return res.end(); }
-  res.writeHead(200, { 'content-type': MIME[path.extname(file)] || 'application/octet-stream' });
-  fs.createReadStream(file).pipe(res);
+  const size = fs.statSync(file).size;
+  const headers = { 'content-type': MIME[path.extname(file)] || 'application/octet-stream', 'content-length': size };
+  let start = 0, end = size - 1, status = 200;
+  if (path.extname(file) === '.mp4') {
+    headers['accept-ranges'] = 'bytes';
+    if (req.headers?.range && req.method !== 'HEAD') {
+      const match = /^bytes=(\d*)-(\d*)$/.exec(req.headers.range);
+      if (match && (match[1] || match[2])) {
+        start = match[1] ? Number(match[1]) : Math.max(0, size - Number(match[2]));
+        end = match[1] && match[2] ? Math.min(size - 1, Number(match[2])) : size - 1;
+      } else start = size;
+      if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start >= size || end < start) {
+        res.writeHead(416, { 'content-range': `bytes */${size}` }); return res.end();
+      }
+      status = 206;
+      headers['content-range'] = `bytes ${start}-${end}/${size}`;
+      headers['content-length'] = end - start + 1;
+    }
+  }
+  res.writeHead(status, headers);
+  if (req.method === 'HEAD' || size === 0) return res.end();
+  const stream = fs.createReadStream(file, { start, end });
+  stream.on('error', () => res.destroy());
+  res.on('close', () => stream.destroy());
+  stream.pipe(res);
 }
 
 // A bare static server for `library ui --serve` — same content http.mjs serves at `/`,
 // without `/mcp` or `/healthz`.
 export async function serveStatic(root, port) {
   const srv = http.createServer((req, res) => {
-    serveFile(root, req.url, res);
+    serveFile(root, req.url, res, req);
   });
   await new Promise((resolve, reject) => { srv.once('error', reject); srv.listen(port, resolve); });
   process.stderr.write(`wp-design-library: ui on :${port}\n`);

package/src/ui/templates/entry.html

@@ -6,7 +6,12 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <style>
   body { font: 14px/1.5 system-ui, sans-serif; max-width: 60rem; margin: 0 auto; padding: 1rem; }
-  img { max-width: 100%; border-radius: 8px; }
+  img, video { max-width: 100%; border-radius: 8px; }
+  video { display: block; width: 100%; height: auto; background: #171717; }
+  .motion-clip { margin: 1.5rem 0; }
+  .motion-frames { display: flex; gap: .75rem; overflow-x: auto; padding: .75rem 0; }
+  .motion-frames figure { flex: 0 0 200px; margin: 0; }
+  .motion-frames figcaption { font-variant-numeric: tabular-nums; }
   dl { display: grid; grid-template-columns: 8rem 1fr; gap: .25rem 1rem; }
   dt { font-weight: 600; }
   .badge { background: #d33; color: #fff; font-size: .7em; padding: .1em .4em; border-radius: 4px; }
@@ -15,6 +20,7 @@
 <body>
 <p><a href="../index.html">&larr; back to the gallery</a></p>
 <h1>{{TITLE}} {{DRAFT_BADGE}}</h1>
+{{MOTION_CLIPS}}
 {{STRIP_IMG}}
 <dl>
 <dt>Tier</dt><dd>{{TIER}}</dd>
@@ -22,8 +28,10 @@
 <dt>Feel</dt><dd>{{FEEL}}</dd>
 <dt>Motion</dt><dd>{{MOTION}}</dd>
 <dt>Source</dt><dd>{{SOURCE}}</dd>
+{{SITE_ROW}}
 <dt>Licence</dt><dd>{{LICENSE}}</dd>
 <dt>Captured</dt><dd>{{CAPTURED}}</dd>
+{{CAPTURES_ROW}}
 </dl>
 {{MEASUREMENTS}}
 {{BODY}}

package/tests/README.md

@@ -1,33 +0,0 @@
-# Check ports
-
-A check that starts `serve --http` picks its own `PORT`, unique across the suite, so
-checks can run concurrently without colliding on a listening socket.
-
-| Check | Port |
-|---|---|
-| fetch-on-start.sh | 4189 |
-| minors.sh | 4190 |
-| similar.sh | 4191 |
-| ui-build.sh | 4193 |
-| hygiene.sh | 4195 |
-| seed-sync.sh | 4196 |
-| docker.sh | 4198 |
-| http.sh | 4199 |
-
-A check that never calls `serve --http` (everything else under `tests/checks/`) needs
-no port; it exercises `add`/`export`/`index`/`check`/`save` directly or drives `serve`
-(no `--http`) over stdio.
-
-A new serve-based check takes the next free port below 4191.
-
-## Checks with no port
-
-`instructions.sh`, `entry-detail.sh` and `recommend.sh` drive the server over stdio
-(`serve`, no `--http`) and start no server on a fixed port, so the table above is
-unchanged by them.
-
-| Check | Asserts |
-|---|---|
-| instructions.sh | the `initialize` response's `instructions`: present, under the 1500-char budget, and carrying the colour fence, the project-wins line, the call budget, and the `ranks.fts` explanation |
-| entry-detail.sh | `get_entry`'s `detail: "summary"` returns a strictly shorter body than `detail: "full"` for the same slug, with matching frontmatter and strip path |
-| recommend.sh | `recommend` returns one group per vocabulary role, weak hits marked, no prose bodies, and the same named-reason degradation `search` already gives when the vector arm is absent |

package/tests/checks/cli-check.sh

@@ -1,13 +0,0 @@
-#!/usr/bin/env bash
-set -eu
-cd "$(dirname "$0")/../.."
-tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
-mkdir -p "$tmp/entries"; cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
-LIBRARY_DATA="$tmp" node bin/library.mjs check | grep -q "1/1 entries ok" || { echo "FAIL: clean corpus"; exit 1; }
-sed -i 's/kind: open/kind: paid/; s/tier: inspiration/tier: ported/' "$tmp/entries/entry-ok/entry.md"
-if LIBRARY_DATA="$tmp" node bin/library.mjs check >"$tmp/out" 2>&1; then echo "FAIL: gate not enforced by check"; exit 1; fi
-grep -q "entry-ok: licence gate" "$tmp/out" || { echo "FAIL: error line shape"; cat "$tmp/out"; exit 1; }
-mkdir -p "$tmp/entries/broken"; echo "no frontmatter here" > "$tmp/entries/broken/entry.md"
-if LIBRARY_DATA="$tmp" node bin/library.mjs check >"$tmp/out" 2>&1; then echo "FAIL: parse error not detected"; exit 1; fi
-grep -q "^broken: " "$tmp/out" || { echo "FAIL: parse error line shape"; cat "$tmp/out"; exit 1; }
-echo PASS

package/tests/checks/docker.sh

@@ -1,10 +0,0 @@
-#!/usr/bin/env bash
-set -eu
-cd "$(dirname "$0")/../.."
-command -v docker >/dev/null || { echo "SKIP: docker not installed"; exit 0; }
-docker build -q -t wp-design-library:check . >/dev/null
-cid=""; trap '[ -n "$cid" ] && docker stop "$cid" >/dev/null 2>&1 || true' EXIT
-cid=$(docker run -d --rm -e LIBRARY_TOKEN=t0k -p 4198:4180 wp-design-library:check)
-for i in $(seq 1 60); do curl -sf localhost:4198/healthz >/dev/null 2>&1 && break; sleep 1; done
-curl -sf localhost:4198/healthz | grep -q '"ok":true' || { echo "FAIL: container healthz"; docker logs "$cid"; exit 1; }
-echo PASS

package/tests/checks/entry-detail.sh

@@ -1,52 +0,0 @@
-#!/usr/bin/env bash
-# summary returns a strictly shorter body than full for the same slug, and both
-# carry the same frontmatter and strip path — a summary that dropped either would
-# be a different tool, not a cheaper one.
-set -eu
-cd "$(dirname "$0")/../.."
-tmp=$(mktemp -d); export LIBRARY_SEED="$tmp/noseed"; trap 'rm -rf "$tmp"' EXIT
-mkdir -p "$tmp/entries"; cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
-LIBRARY_DATA="$tmp" node bin/library.mjs index >/dev/null 2>&1
-{
-  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}'
-  printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'
-  printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_entry","arguments":{"slug":"entry-ok"}}}'
-  printf '%s\n' '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_entry","arguments":{"slug":"entry-ok","detail":"summary"}}}'
-  sleep 1
-} | LIBRARY_DATA="$tmp" timeout 20 node bin/library.mjs serve >"$tmp/out" 2>"$tmp/err" || true
-
-node --input-type=module -e '
-import fs from "node:fs";
-const byId = {};
-for (const line of fs.readFileSync(process.argv[1], "utf8").split("\n")) {
-  if (!line.startsWith("{")) continue;
-  const d = JSON.parse(line);
-  if (d.id) byId[d.id] = d;
-}
-const fail = (m) => { console.error("FAIL: " + m); process.exit(1); };
-const full = byId[2]?.result?.structuredContent;
-const sum  = byId[3]?.result?.structuredContent;
-if (!full) fail("no full result");
-if (!sum) fail("no summary result");
-if (typeof sum.body !== "string") fail("summary has no body");
-if (!(sum.body.length < full.body.length)) fail(`summary body (${sum.body.length}) is not shorter than full (${full.body.length})`);
-if (/^\s*#/.test(sum.body)) fail(`summary is a bare heading, not prose: ${JSON.stringify(sum.body)}`);
-if (/\n\s*\n/.test(sum.body)) fail(`summary spans a paragraph break, so it is a truncation not a paragraph: ${JSON.stringify(sum.body)}`);
-if (/^\s*#/m.test(sum.body)) fail(`summary contains a heading line: ${JSON.stringify(sum.body)}`);
-if (sum.body.trim().length < 20) fail(`summary is too short to decide from: ${JSON.stringify(sum.body)}`);
-if (sum.detail !== "summary") fail("summary result is not labelled detail:summary");
-if (sum.strip !== full.strip) fail("summary lost the strip path");
-if (JSON.stringify(sum.fm) !== JSON.stringify(full.fm)) fail("summary changed the frontmatter");
-// A splitter that FILTERS every prose paragraph and joins them (instead of taking
-// just the first) can still pass every assertion above: joined with a space instead
-// of a blank line, it dodges the paragraph-break check, and it is still shorter than
-// full because only headings were dropped. Pin the actual promise: summary is a
-// PREFIX of full body, and a later prose paragraph never appears in it.
-if (!full.body.includes(sum.body)) fail(`summary is not a substring of full body: ${JSON.stringify(sum.body)}`);
-const fullProse = full.body.trim().split(/\n\s*\n/).filter((x) => !/^\s*#/.test(x));
-if (fullProse.length < 2) fail("fixture needs more than one prose paragraph to exercise this assertion");
-const later = fullProse[fullProse.length - 1];
-if (sum.body.includes(later)) fail(`summary includes a later prose paragraph, so it did not stop at the first: ${JSON.stringify(later)}`);
-console.log(`full ${full.body.length} chars, summary ${sum.body.length}`);
-' "$tmp/out" || { cat "$tmp/err"; exit 1; }
-echo PASS

package/tests/checks/entry.sh

@@ -1,55 +0,0 @@
-#!/usr/bin/env bash
-set -eu
-cd "$(dirname "$0")/../.."
-node --input-type=module -e '
-import { parseEntry, validateEntry } from "./src/entry.mjs";
-import { loadVocab } from "./src/vocab.mjs";
-const must = (c, m) => { if (!c) { console.error("FAIL: " + m); process.exit(1); } };
-const v = loadVocab();
-const e = parseEntry("tests/fixtures/entry-ok");
-must(e.slug === "entry-ok", "slug from frontmatter");
-must(e.body.includes("## Section roster"), "body parsed");
-let r = validateEntry(e, v);
-must(r.ok, "fixture validates: " + r.errors.join("; "));
-e.fm.roles = ["hero", "neon"];
-r = validateEntry(e, v);
-must(!r.ok && r.errors.some(x => x.includes("role") && x.includes("neon")), "unknown tag names facet and term");
-e.fm.roles = ["plans"];
-r = validateEntry(e, v);
-must(r.ok && e.fm.roles[0] === "offer", "alias resolved to canonical in place");
-e.fm.title = "";
-r = validateEntry(e, v);
-must(!r.ok && r.errors.some(x => x.includes("title")), "blank required field named");
-'
-
-# Test CRLF line endings support
-tmpdir=$(mktemp -d)
-trap "rm -rf $tmpdir" EXIT
-mkdir -p "$tmpdir/entry-ok"
-cp tests/fixtures/entry-ok/entry.md "$tmpdir/entry-ok/entry.md"
-sed -i "s/$/\r/" "$tmpdir/entry-ok/entry.md"
-cp tests/fixtures/entry-ok/strip.png "$tmpdir/entry-ok/strip.png"
-node --input-type=module -e "
-import { parseEntry, validateEntry } from './src/entry.mjs';
-import { loadVocab } from './src/vocab.mjs';
-const must = (c, m) => { if (!c) { console.error('FAIL: ' + m); process.exit(1); } };
-const v = loadVocab();
-const e = parseEntry('$tmpdir/entry-ok');
-must(e.slug === 'entry-ok', 'CRLF: slug parsed');
-must(validateEntry(e, v).ok, 'CRLF: validates');
-"
-
-# slug must equal the directory name
-mkdir -p "$tmpdir/other-name"
-cp tests/fixtures/entry-ok/entry.md tests/fixtures/entry-ok/strip.png "$tmpdir/other-name/"
-node --input-type=module -e "
-import { parseEntry, validateEntry } from './src/entry.mjs';
-import { loadVocab } from './src/vocab.mjs';
-const must = (c, m) => { if (!c) { console.error('FAIL: ' + m); process.exit(1); } };
-const v = loadVocab();
-const e = parseEntry('$tmpdir/other-name');
-const r = validateEntry(e, v);
-must(!r.ok && r.errors.some(x => x.includes('slug: must equal')), 'slug mismatch refused');
-"
-
-echo PASS

package/tests/checks/export.sh

@@ -1,16 +0,0 @@
-#!/usr/bin/env bash
-set -eu
-cd "$(dirname "$0")/../.."
-node_bin=$(command -v node)
-tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
-mkdir -p "$tmp/entries"; cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
-LIBRARY_DATA="$tmp" node bin/library.mjs export > "$tmp/out.tar" 2>"$tmp/err"
-tar -tf "$tmp/out.tar" | grep -q 'entries/entry-ok/entry.md' || { echo "FAIL: tar content"; exit 1; }
-grep -q "export: 1 entries" "$tmp/err" || { echo "FAIL: count on stderr"; exit 1; }
-
-emptybin="$tmp/emptybin"; mkdir -p "$emptybin"
-code=0
-PATH="$emptybin" LIBRARY_DATA="$tmp" "$node_bin" bin/library.mjs export > "$tmp/out2.tar" 2>"$tmp/err2" || code=$?
-[ "$code" -ne 0 ] || { echo "FAIL: missing tar should exit non-zero"; exit 1; }
-grep -q "tar is required" "$tmp/err2" || { echo "FAIL: missing tar message"; cat "$tmp/err2"; exit 1; }
-echo PASS