@yojahny/wp-design-library 0.3.0 → 0.5.1

package/entries/thoughtlab/captures/2/measure.json

@@ -0,0 +1,93 @@
+{
+  "url": "https://www.thoughtlab.com/",
+  "at": "2026-09-16",
+  "viewport": [
+    1440,
+    390
+  ],
+  "tokens": {
+    "canvas": "#000000",
+    "ink": "#cccccc",
+    "accent": "#ffffff",
+    "fontDisplay": "sui",
+    "fontBody": "sui"
+  },
+  "sections": [
+    {
+      "index": 0,
+      "tag": "header",
+      "id": "",
+      "class": "sh fix top left x pt30",
+      "top": 0,
+      "height": 72,
+      "animations": []
+    },
+    {
+      "index": 1,
+      "tag": "article",
+      "id": "home",
+      "class": "",
+      "top": 0,
+      "height": 8966,
+      "animations": []
+    },
+    {
+      "index": 2,
+      "tag": "section",
+      "id": "",
+      "class": "hero rel x",
+      "top": 0,
+      "height": 900,
+      "animations": []
+    },
+    {
+      "index": 3,
+      "tag": "section",
+      "id": "",
+      "class": "js-sel mb30 s:mb150",
+      "top": 900,
+      "height": 2700,
+      "animations": []
+    },
+    {
+      "index": 4,
+      "tag": "section",
+      "id": "",
+      "class": "caps mb60 s:mb150 rel",
+      "top": 4626,
+      "height": 626,
+      "animations": []
+    },
+    {
+      "index": 5,
+      "tag": "section",
+      "id": "",
+      "class": "news-list",
+      "top": 5469,
+      "height": 2219,
+      "animations": []
+    },
+    {
+      "index": 6,
+      "tag": "section",
+      "id": "",
+      "class": "h-contact",
+      "top": 7688,
+      "height": 819,
+      "animations": []
+    },
+    {
+      "index": 7,
+      "tag": "footer",
+      "id": "",
+      "class": "sf  pb45 c-white",
+      "top": 8651,
+      "height": 315,
+      "animations": []
+    }
+  ],
+  "screenshots": {
+    "390": "screen-390.png",
+    "1440": "screen-1440.png"
+  }
+}

package/entries/thoughtlab/entry.md

@@ -0,0 +1,62 @@
+---
+slug: thoughtlab
+title: 'ThoughtLab: data-led consulting landing'
+tier: inspiration
+source:
+  kind: public-site
+  url: https://www.thoughtlab.com/
+  license: Captured from a Refero-hosted recording and the live site; description only, no redistribution of the source.
+captured:
+  method: both
+  at: '2026-09-16'
+  tool: wp-design-library@0.4.0
+  captures:
+    - method: frames
+      input: /tmp/thoughtlab-refero.mp4
+      artifacts:
+        - strip.webp
+      frames: 36
+      duration_ms: 24533
+    - method: both
+      input: https://www.thoughtlab.com/
+      artifacts:
+        - captures/2/strip.webp
+        - captures/2/measure.json
+        - captures/2/screen-1440.png
+        - captures/2/screen-390.png
+media:
+  frames: 36
+  duration_ms: 24533
+roles: [hero, feature, capability, proof, closing, footer]
+feel: [dark, premium, editorial, depth, cold]
+palette:
+  canvas: '#000000'
+  ink: '#cccccc'
+  accent: '#ff2257'
+type:
+  display: sui
+  body: sui
+motion:
+  devices: [reveal, pan, drift, wipe, tabs]
+  notes: 'The supplied recording moves through a sequence of project names while irregular glass-like image portals change their internal imagery and edge light. Large condensed labels reveal beside each portal, then the composition wipes to the next case. The live capture confirms the hero portal and fixed header, but does not expose CSS animation records or individual input triggers.'
+ported_from: null
+---
+
+## What it does
+
+ThoughtLab presents category-first brand and product work as a dark portfolio sequence. One large organic portal acts as a moving canvas for selected cases, followed by capability, news, and contact sections.
+
+## Section roster
+
+1. Fixed logo, partnership claim, contact action, and dark hero with an irregular reflective portal.
+2. Selected-work sequence cycling Wander Jaunt, Varex Imaging, Capsule House, and other case imagery.
+3. Capability statement and proof/content sections.
+4. News list, contact prompt, and compact footer.
+
+## Why it works
+
+The evolving portal gives every case a shared visual frame while keeping the page sparse. Black space, silver type, and a single hot-pink action make the content feel like a studio reel instead of a conventional agency grid.
+
+## Sources
+
+The Refero MP4 at https://images.refero.design/styles/refero.design/video/504bf76a-aab7-459c-9496-1f520fd0324a.mp4 provides the 24.53-second project sequence and portal transitions. The live capture at https://www.thoughtlab.com/ supplies current desktop/mobile layout and measured tokens. Both sources show the same dark portfolio direction.

package/entries/ventriloc/entry.md

@@ -0,0 +1,54 @@
+---
+slug: ventriloc
+title: 'Ventriloc: business intelligence platform'
+tier: inspiration
+source:
+  kind: public-site
+  url: https://ventriloc.ca/en
+  license: Captured from a Refero-hosted recording and the live site; description only, no redistribution of the source.
+captured:
+  method: frames
+  at: '2026-09-16'
+  tool: wp-design-library@0.4.0
+  captures:
+    - method: frames
+      input: /tmp/ventriloc-refero.mp4
+      artifacts:
+        - strip.webp
+      frames: 36
+      duration_ms: 6567
+media:
+  frames: 36
+  duration_ms: 6567
+roles: [hero, proof, feature]
+feel: [light, premium, saas, minimal]
+palette:
+  canvas: '#f5f5f5'
+  ink: '#202020'
+  accent: '#828282'
+type:
+  display: PolySans, sans-serif
+  body: Inter, sans-serif
+motion:
+  devices: [reveal, pan]
+  notes: Eyeballed from 36 sampled frames, not measured. Dashboard cards and chart lines animate into the right side of the hero while the headline stays anchored on the left; later sampled frames show the metric states changing. Individual triggers are not visible.
+ported_from: null
+---
+
+## What it does
+
+Ventriloc presents business intelligence as a clean analytics-led growth service.
+
+## Section roster
+
+1. Split hero with analytics promise, actions, and animated chart cards.
+2. Partner-logo proof row.
+3. Dashboard metric demonstration.
+
+## Why it works
+
+The restrained page gives its charts plenty of space, making the data cards feel like evidence rather than visual filler. The minimal treatment asks the headline to carry most of the personality.
+
+## Sources
+
+The Refero MP4 supplies the sampled motion sequence. https://ventriloc.ca/en remains the source URL; its incomplete live render was not retained as a capture.

package/entries/vivid-and-co/entry.md

@@ -0,0 +1,58 @@
+---
+slug: vivid-and-co
+title: 'Vivid & Co.: refractive creative-studio landing'
+tier: inspiration
+source:
+  kind: public-site
+  url: https://vividand.co/
+  license: Captured from the supplied recording and live site; description only, no redistribution of the source.
+captured:
+  method: frames
+  at: '2026-09-16'
+  tool: wp-design-library@0.4.0
+  captures:
+    - method: frames
+      input: /home/yojahny/Desktop/inspiration/evivid.mp4
+      artifacts:
+        - strip.webp
+      frames: 36
+      duration_ms: 36833
+media:
+  frames: 36
+  duration_ms: 36833
+roles: [hero, explainer, capability, proof, closing, footer]
+feel: [dark, premium, editorial, minimal, depth, cold]
+palette:
+  canvas: '#101010'
+  ink: '#fffdf9'
+  accent: '#67d8ff'
+type:
+  display: '"Neue Montreal"'
+  body: '"Neue Montreal", sans-serif'
+motion:
+  devices: [reveal, pan, drift, stagger, wipe]
+  notes: 'The supplied recording shows a refractive block assembly slowly rotating and drifting through the opening statements, while large type changes in staged fragments around it. Each chapter uses a restrained fade or wipe into a new text composition; the prismatic light field remains as a connecting layer. The live capture records a long sequence of SVG animations across the page. It confirms that the chromatic object and surrounding graphic treatment are animated, but this capture does not establish individual interaction triggers.'
+ported_from: null
+---
+
+## What it does
+
+Vivid & Co. introduces a full-service agency and strategic advisor through large, declarative statements instead of a project grid. A black, lightly textured field carries minimal white type, small proof details, and a recurring translucent object whose rainbow edges add movement and depth.
+
+## Section roster
+
+1. Compact header with expertise, work, team, careers, and contact navigation.
+2. Hero that introduces Vivid & Co. beside the refractive block assembly.
+3. Brand-value statement and a large argument for integrated strategy, PR, and creative identity.
+4. Expertise and process sections with sparse text blocks, sector labels, and the moving object.
+5. Client and press proof row.
+6. Team introduction, people profile, advisor/investor list, and careers close.
+7. Contact-led footer.
+
+## Why it works
+
+The interface has the pacing of a short title sequence. Each large statement gets an uncluttered frame, then the page uses small supporting copy and hairline dividers to reset the scale. The glass-like object concentrates the site’s color, so the rest of the layout can stay almost monochrome without feeling flat.
+
+## Sources
+
+The supplied 36.83-second recording provides the complete desktop sequence, including the changing opening statements, object movement, expertise/process copy, proof row, team profile, advisors, and closing. The live capture at https://vividand.co/ supplies the current desktop and mobile layouts, measured type/tokens, and the page-wide SVG animation evidence. Both sources show the same black editorial direction and prismatic-object treatment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yojahny/wp-design-library",
-  "version": "0.3.0",
+  "version": "0.5.1",
   "description": "Design reference corpus and MCP server for claude-wp-builder",
   "repository": {
     "type": "git",
@@ -55,8 +55,27 @@
     "docker-compose.yml",
     "docker/",
     "entries/",
-    "src/",
-    "tests/",
-    "vocab.yaml"
-  ]
+    "src/cli/add.mjs",
+    "src/cli/check.mjs",
+    "src/cli/export.mjs",
+    "src/cli/index.mjs",
+    "src/cli/motion.mjs",
+    "src/cli/refresh.mjs",
+    "src/cli/save.mjs",
+    "src/cli/serve.mjs",
+    "src/cli/ui.mjs",
+    "src/entry.mjs",
+    "src/index/",
+    "src/ingest/",
+    "src/mcp/",
+    "src/motion.mjs",
+    "src/paths.mjs",
+    "src/ui/",
+    "src/vocab.mjs",
+    "vocab.yaml",
+    "!entries/**/screen-*.png"
+  ],
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1134.0"
+  }
 }

package/src/cli/add.mjs

@@ -1,29 +1,48 @@
 import path from 'node:path';
+import { existsSync } from 'node:fs';
 import sharp from 'sharp';
 import { paths } from '../paths.mjs';
-import { sampleFrames, compositeStrip } from '../ingest/frames.mjs';
+import { sampleFrames, compositeStrip, writeStrip } from '../ingest/frames.mjs';
 import { writeDraft } from '../ingest/draft.mjs';
+import { attachCapture } from '../ingest/attach.mjs';
 import { measure } from '../ingest/measure.mjs';
 import { loadVocab, resolveTerm } from '../vocab.mjs';
+import { parseEntry } from '../entry.mjs';
 
 function opt(args, name) { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; }
 
+// captures/<n>/ where n is the new capture's 1-based position. Capture 1 has no directory —
+// its files stay at the entry root, so existing entries and get_entry's `strip` are untouched.
+function captureDir(dir, index) {
+  return index === 1 ? dir : path.join(dir, 'captures', String(index));
+}
+
+// The new capture's 1-based position. An entry written before captures[] existed has one
+// capture recorded in its top-level fields, so it counts as 1 and the new one is 2. An entry
+// that EXISTS can never yield 1: index===1 is the wipe trigger, so a hand-written
+// `captures: []` would otherwise turn --attach into --force and destroy the entry.
+function nextCaptureIndex(dir) {
+  if (!existsSync(path.join(dir, 'entry.md'))) return 1;
+  const { fm } = parseEntry(dir);
+  return Math.max(fm.captured?.captures?.length ?? 1, 1) + 1;
+}
+
 const MEDIA = /\.(webp|gif|mp4|mov|webm|mkv)$/i;
 const URL_RE = /^(https?:\/\/|file:\/\/)/;
 function slugify(name) { return name.replace(/\.[^.]+$/, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, ''); }
 
-// Composites recorded scroll-stop screenshots into a strip.png the same way sampleFrames
+// Composites recorded scroll-stop screenshots into a strip.webp the same way sampleFrames
 // does for video/animated-image input.
-async function stripFromFrames(framePaths, outPng) {
+async function stripFromFrames(framePaths, out) {
   const tiles = await Promise.all(framePaths.map((f) => sharp(f).png().toBuffer()));
   const first = await sharp(framePaths[0]).metadata();
-  await compositeStrip(tiles, first.width, first.height, outPng);
+  await compositeStrip(tiles, first.width, first.height, out);
 }
 
 // URL/file:// input: measure the live page with system Chrome instead of sampling
 // frames from a recording. Scratch-dir-first, same as the frame path: a total
 // failure (nothing captured at all) must leave nothing under entries/.
-async function addFromUrl({ p, input, slug, title, source, dir, record }) {
+async function addFromUrl({ p, input, slug, title, source, dir, record, force, attach }) {
   const fs = await import('node:fs');
   const os = await import('node:os');
   const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'wpdl-add-'));
@@ -41,32 +60,61 @@ async function addFromUrl({ p, input, slug, title, source, dir, record }) {
 
   const today = new Date().toISOString().slice(0, 10);
   const tool = `wp-design-library@${p.version}`;
-  fs.mkdirSync(dir, { recursive: true });
-  const strip = path.join(dir, 'strip.png');
+  // force always wipes and recreates as capture 1, exactly as it does today, regardless of
+  // attach; only a plain attach (no force) merges onto the existing capture list.
+  const index = (!force && attach) ? nextCaptureIndex(dir) : 1;
+  // Composite into scratch first, same as the frame path: every byte of the new capture has to
+  // exist before anything under entries/ is touched. sharp can fail on a recorded frame well
+  // after measure() returned usable data, and the wipe below is unrecoverable.
+  const scratchStrip = path.join(scratch, 'strip.webp');
   let captured, palette, type;
   if (result.ok) {
     captured = { method: record ? 'both' : 'measured', at: today, tool };
     const t = result.measure.tokens;
     palette = { canvas: t.canvas || '', ink: t.ink || '', accent: t.accent || '' };
     type = { display: t.fontDisplay || '', body: t.fontBody || '' };
-    if (record && result.frames?.length) await stripFromFrames(result.frames, strip);
-    else fs.copyFileSync(result.screenshots[1440], strip);
-    for (const f of ['measure.json', 'screen-1440.png', 'screen-390.png']) {
-      fs.copyFileSync(path.join(scratch, f), path.join(dir, f));
-    }
+    if (record && result.frames?.length) await stripFromFrames(result.frames, scratchStrip);
+    else await writeStrip(sharp(result.screenshots[1440]), scratchStrip);
   } else {
     // record succeeded but the token/section measurement itself failed: keep the
     // frames (spec §11), label the method accordingly, and record why.
     captured = { method: 'frames', at: today, tool, error: result.error };
-    await stripFromFrames(result.frames, strip);
+    await stripFromFrames(result.frames, scratchStrip);
+  }
+
+  // Gated on index, not force directly: index===1 is the same decision the attach-vs-recreate
+  // branch below acts on, so the two can never disagree — a regression that breaks the line
+  // above (force stops forcing index to 1) also stops this wipe from firing, instead of wiping
+  // a directory out from under a capture the buggy code is about to attach to. It fires only
+  // here, below the compositing, so nothing between measure() and a written strip can destroy
+  // an existing entry and leave nothing in its place; what follows is copies out of scratch.
+  if (index === 1) fs.rmSync(dir, { recursive: true, force: true });
+  const outDir = captureDir(dir, index);
+  fs.mkdirSync(outDir, { recursive: true });
+  const strip = path.join(outDir, 'strip.webp');
+  fs.copyFileSync(scratchStrip, strip);
+  if (result.ok) {
+    for (const f of ['measure.json', 'screen-1440.png', 'screen-390.png']) {
+      fs.copyFileSync(path.join(scratch, f), path.join(outDir, f));
+    }
   }
   fs.rmSync(scratch, { recursive: true, force: true });
 
-  const d = writeDraft({ entriesDir: p.entries, slug, title, source: { ...source, url: source.url ?? input }, media: {}, captured, palette, type });
+  const artifactNames = ['strip.webp'];
+  if (result.ok) artifactNames.push('measure.json', 'screen-1440.png', 'screen-390.png');
+  const artifacts = artifactNames.map((f) => path.relative(dir, path.join(outDir, f)));
+  const capture = { method: captured.method, input, artifacts };
+
+  if (index > 1) {
+    const r = await attachCapture({ entriesDir: p.entries, slug, capture, palette, type, sourceUrl: input, tool });
+    return { dir: r.dir, strip, captures: r.captures.length, measured: result.ok };
+  }
+
+  const d = writeDraft({ entriesDir: p.entries, slug, title, source: { ...source, url: source.url ?? input }, media: {}, captured, palette, type, captures: [capture] });
   return { dir: d.dir, strip, blanks: d.blanks, measured: result.ok };
 }
 
-export async function addEntry({ input, slug, title, source, force = false, frames, record = false }) {
+export async function addEntry({ input, slug, title, source, force = false, frames, record = false, attach = false }) {
   const p = paths();
   if (!input || !slug || !title || !source?.kind || !source?.license) throw new Error('add: input, slug, title, --source and --license are required');
   // Refused here (draft time), not first at save: resolveTerm is the single vocab gate
@@ -75,17 +123,18 @@ export async function addEntry({ input, slug, title, source, force = false, fram
     return { refused: `source.kind: unknown source term "${source.kind}"` };
   }
   const dir = path.join(p.entries, slug);
-  const { mkdirSync, mkdtempSync, existsSync, renameSync, copyFileSync, unlinkSync, rmSync } = await import('node:fs');
+  const { mkdirSync, mkdtempSync, renameSync, copyFileSync, unlinkSync, rmSync } = await import('node:fs');
   const os = await import('node:os');
-  if (existsSync(path.join(dir, 'entry.md')) && !force) {
-    return { refused: `entry ${slug} exists; pass force to overwrite` };
+  const exists = existsSync(path.join(dir, 'entry.md'));
+  if (exists && !force && !attach) {
+    return { refused: `entry ${slug} exists; pass attach to add a capture, or force to overwrite` };
   }
   if (URL_RE.test(input)) {
-    return addFromUrl({ p, input, slug, title, source, dir, record });
+    return addFromUrl({ p, input, slug, title, source, dir, record, force, attach });
   }
   // Sample into a scratch dir first: a refusal must leave nothing under entries/.
   const scratch = mkdtempSync(path.join(os.tmpdir(), 'wpdl-add-'));
-  const scratchStrip = path.join(scratch, 'strip.png');
+  const scratchStrip = path.join(scratch, 'strip.webp');
   let media;
   try {
     media = await sampleFrames(input, scratchStrip, { frames });
@@ -94,8 +143,20 @@ export async function addEntry({ input, slug, title, source, force = false, fram
     if (err.message?.startsWith('ffmpeg')) return { refused: err.message };
     throw err;
   }
-  mkdirSync(dir, { recursive: true });
-  const strip = path.join(dir, 'strip.png');
+  // force always wipes and recreates as capture 1, exactly as it does today, regardless of
+  // attach; only a plain attach (no force) merges onto the existing capture list.
+  const index = (!force && attach) ? nextCaptureIndex(dir) : 1;
+  // Gated on index, not force directly: index===1 is the same decision the attach-vs-recreate
+  // branch below acts on, so the two can never disagree — a regression that breaks the line
+  // above (force stops forcing index to 1) also stops this wipe from firing, instead of wiping
+  // a directory out from under a capture the buggy code is about to attach to. The wipe happens
+  // only here — after sampleFrames has already succeeded into scratch (a sampling failure above
+  // is already handled by the catch block) — so it can never destroy an existing entry and
+  // leave nothing in its place.
+  if (index === 1) rmSync(dir, { recursive: true, force: true });
+  const outDir = captureDir(dir, index);
+  mkdirSync(outDir, { recursive: true });
+  const strip = path.join(outDir, 'strip.webp');
   try {
     renameSync(scratchStrip, strip);
   } catch {
@@ -103,8 +164,22 @@ export async function addEntry({ input, slug, title, source, force = false, fram
     unlinkSync(scratchStrip);
   }
   rmSync(scratch, { recursive: true, force: true });
-  const captured = { method: 'frames', at: new Date().toISOString().slice(0, 10), tool: `wp-design-library@${p.version}` };
-  const d = writeDraft({ entriesDir: p.entries, slug, title, source, media: { frames: media.frames, duration_ms: media.durationMs }, captured });
+
+  const rel = path.relative(dir, strip);
+  const capture = {
+    method: 'frames', input, artifacts: [rel],
+    frames: media.frames, duration_ms: media.durationMs,
+  };
+  const mediaFields = { frames: media.frames, duration_ms: media.durationMs };
+  const tool = `wp-design-library@${p.version}`;
+
+  if (index > 1) {
+    const r = await attachCapture({ entriesDir: p.entries, slug, capture, media: mediaFields, tool });
+    return { dir: r.dir, strip, captures: r.captures.length, frames: media.frames };
+  }
+
+  const captured = { method: 'frames', at: new Date().toISOString().slice(0, 10), tool };
+  const d = writeDraft({ entriesDir: p.entries, slug, title, source, media: mediaFields, captured, captures: [capture] });
   return { dir: d.dir, strip, blanks: d.blanks, frames: media.frames };
 }
 
@@ -157,6 +232,7 @@ export async function run(args) {
     force: args.includes('--force'),
     frames,
     record: args.includes('--record'),
+    attach: args.includes('--attach'),
   });
   process.stdout.write(JSON.stringify(out) + '\n');
   return out.refused ? 1 : 0;