@yojahny/wp-design-library 0.3.0 → 0.5.1

package/.env.example

@@ -5,3 +5,10 @@ LIBRARY_FETCH_MODELS=0    # 1 = fetch the vector-search models on server start (
 LIBRARY_MODELS=/data/models    # where the models land on the /data volume
 LIBRARY_EMBED=    # empty = real models when present, stub = deterministic vectors for checks, off = FTS only
 CHROME_SANDBOX=0    # 1 = let Chrome use its own sandbox; only where user namespaces are allowed (not the default container)
+
+# Internal motion publisher only; never used by the public UI or MCP readers.
+R2_ACCOUNT_ID=
+R2_ACCESS_KEY_ID=
+R2_SECRET_ACCESS_KEY=
+R2_BUCKET=
+R2_PUBLIC_BASE_URL=

package/README.md

@@ -72,7 +72,7 @@ node bin/library.mjs add ~/Desktop/site.webp \
 | `--license` | free text, required; say what you may do with it |
 | `--force` | overwrite an existing draft (otherwise a second `add` is refused) |
 
-This writes `entries/<slug>/strip.png` (6–12 sampled frames) and a draft
+This writes `entries/<slug>/strip.webp` (6–12 sampled frames) and a draft
 `entries/<slug>/entry.md` with the mechanical fields filled and every
 judgement field blank. The output lists those blanks:
 
@@ -102,7 +102,7 @@ CHROME_PATH=/usr/bin/google-chrome node bin/library.mjs add https://acme.example
 
 | Flag | Meaning |
 |---|---|
-| `--record` | also scroll top to bottom in 12 steps at 1440 and build `strip.png` from those stops (`captured.method: both`); without it, `strip.png` is the single 1440 screenshot and `captured.method: measured` |
+| `--record` | also scroll top to bottom in 12 steps at 1440 and build `strip.webp` from those stops (`captured.method: both`); without it, `strip.webp` is the single 1440 screenshot and `captured.method: measured` |
 
 `CHROME_PATH` must point at a Chrome or Chromium binary. Without it (or with a path
 that does not exist) `add` refuses with `chrome not available: …` and nothing is
@@ -118,7 +118,7 @@ node bin/library.mjs refresh acme-live-hero
 
 Re-measures `source.url` with the same system Chrome, rewrites `measure.json` and
 `captured.at`, and reindexes. Every judgement field (`roles`, `feel`, `palette`,
-`type`, `motion`, `body`…) and `strip.png` are left exactly as they were. Refuses an
+`type`, `motion`, `body`…) and `strip.webp` are left exactly as they were. Refuses an
 entry with no `source.url`, or one whose `captured.method` is `frames` (nothing came
 from a URL to re-measure). Over MCP, the same as the `refresh` tool: `{ slug }`.
 
@@ -235,6 +235,12 @@ A ported entry adds `ported/section.html`, `ported/section.css`, a README, and
 `ported_from: <inspiration slug>`. `save` and `index` refuse `tier: ported` on
 a `paid` or `public-site` source, and there is no override flag.
 
+## Motion previews
+
+Entries can include short motion clips with timestamped frames. Entry pages load videos only when played; gallery cards keep their thumbnails. The MCP `get_motion` tool returns observed motion notes, a video URL when published, and timestamped images that agents can inspect without video support. Pass `include_frames: false` for metadata only. Clip titles and notes are included in search and text embeddings.
+
+Preparing clips and publishing them to R2 are repository maintenance tasks. See the [internal motion workflow](https://github.com/yojahny55/wp-design-library/blob/main/docs/internal/motion.md) for setup and review steps.
+
 ## Searching
 
 The plugin does this for you, but from the CLI:
@@ -247,7 +253,8 @@ node bin/library.mjs check         # validate every entry, 1 line per problem
 Over MCP, seven tools: `search` (keyword + facet filters, aliases resolved),
 `get_entry` (pass `detail: "summary"` for just the body's first paragraph, instead of
 the default `"full"`), `similar`, `recommend` (turns a brief into a per-role reference
-set in one call), `add`, `refresh`, `save_entry`. `search` and `similar` carry
+set in one call), `add` (pass `attach` to add a second capture — a video beside a live
+URL — to an existing entry instead of refusing it), `refresh`, `save_entry`. `search` and `similar` carry
 `arms` (which retrieval arms ran; `["fts"]` in Phase 1); any tool may instead respond
 with `refused` and the reason.
 
@@ -377,10 +384,11 @@ root only to `chown` an existing (possibly root-owned) `/data` volume, then drop
 
 ## Releasing
 
-1. Bump `version` in `package.json`.
-2. Tag the release: `git tag vX.Y.Z` (the workflow triggers on any `v*` tag).
-3. Push the tag: `git push origin vX.Y.Z`.
-4. `.github/workflows/publish.yml` runs on that push: checks out, installs with
+1. Add the release's entry to `CHANGELOG.md`.
+2. Bump `version` in `package.json`.
+3. Tag the release: `git tag vX.Y.Z` (the workflow triggers on any `v*` tag).
+4. Push the tag: `git push origin vX.Y.Z`.
+5. `.github/workflows/publish.yml` runs on that push: checks out, installs with
    `npm ci`, runs `npm test`, then `npm publish`. Trusted publishing means no npm
    token lives in this repo — the registry trusts the GitHub Actions run itself via
    OIDC (`id-token: write`).
@@ -407,6 +415,13 @@ without breaking this workflow, since it never uses a token.
 
 ## Known ceilings
 
+- **A strip is a 2400px WebP, and the full-size sheet is not kept.** A six-column
+  contact sheet of 1440-wide frames is 9600x6000; at that size 56 of them are 699 MB
+  and npm cannot build a tarball from them at all. 2400px at quality 80 leaves about
+  400px per frame — a headline and a nav stay readable, body copy does not, and
+  1800px loses the headline too. What a session reads off a strip is therefore the
+  composition, the palette and the shape of the type, not its small print; the source
+  frames are gone, so a re-capture is the only way back to full resolution.
 - **Chrome runs without its own sandbox inside the container.** Docker's default
   seccomp profile blocks the user namespaces Chrome's sandbox needs, so
   `chromiumSandbox: true` would fail to launch there; the non-root container user is
@@ -431,12 +446,40 @@ without breaking this workflow, since it never uses a token.
 - **`detail: "summary"` skips leading headings and takes the first prose paragraph.** An
   entry whose opening paragraph says nothing useful summarises badly. The fix is a better
   entry, not a cleverer splitter.
+- **Dominant colour measures screen time, not design intent.** A strip is frames stitched
+  together, so a colour filling eight seconds of an 8.4-second video dominates whether or not a
+  viewer would call it the palette. `agreement.palette.observed` is a pixel-frequency histogram.
+- **"Address the deltas" is prose.** A check can assert the `## Sources` section exists, never
+  that it is honest. The same ceiling every contract here carries.
+- **`agreement` records what was measured at attach time.** If the session later hand-edits
+  `palette`, `agreement.palette.declared` goes stale: it is a record of the capture, not of the
+  entry's current claim. `observed` goes stale the same way after a re-capture: it is recomputed
+  only on attach, never by `refresh`, which rewrites `measure.json` and bumps `captured.at` while
+  leaving the whole block alone. And `captured.method` has no writer but attach, so hand-removing
+  a capture leaves `method: both` on an entry that now holds only frames captures — the one
+  staleness that changes behaviour rather than only a record, since `method` is what `refresh`
+  gates on.
+- **A frames capture cannot be refreshed.** `refresh` still only re-measures a URL; a newer
+  video is attached, not refreshed. It also refuses outright once an entry has more than one
+  capture: it writes into the entry root, capture 1's slot, and cannot know that is the capture
+  `source.url` describes.
+- **Capture 1 is privileged by the path layout** — its files sit at the entry root — and there
+  is no way to promote capture 2. Two consumers inherit that: image embeddings index the root
+  `strip.webp` only, so `similar` can never match on an attached capture's strip; and the entry
+  page reads the root `measure.json` only, so a frames-first entry with a measured capture
+  attached lists that capture in the Captures row and still shows no "Measured tokens" block.
+- **The page links a URL it never re-checks.** `source.url` is recorded at capture time and
+  rendered thereafter; a link that later rots or changes hands is shown exactly as captured.
+- **Cross-`sharp`-version stability is untested.** `package.json` allows `^0.34.3`, so a minor
+  libvips bump could shift the low-count edge buckets that `observedColours` reports. Entries
+  persist for months, so an `agreement` block recomputed later could legitimately differ from
+  one recorded earlier, with no defect involved.
 
 ## Layout
 
 ```
 entries/<slug>/entry.md   frontmatter + prose (the corpus, reviewable in PRs)
-entries/<slug>/strip.png  contact sheet
+entries/<slug>/strip.webp  contact sheet, capped at 2400px wide (WebP q80)
 vocab.yaml                controlled vocabulary, five facets, aliases
 src/ingest/               frames, draft, save
 src/index/                SQLite FTS5 build and query

package/bin/library.mjs

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
 const cmds = {
   check: () => import('../src/cli/check.mjs'),
   index: () => import('../src/cli/index.mjs'),
@@ -9,7 +12,15 @@ const cmds = {
   export: () => import('../src/cli/export.mjs'),
   ui: () => import('../src/cli/ui.mjs'),
 };
+// Refero discovery is a repository-maintenance tool. The npm package deliberately
+// omits its module, so it is only available from a checkout that contains it.
+if (fs.existsSync(fileURLToPath(new URL('../src/cli/refero.mjs', import.meta.url)))) {
+  cmds.refero = () => import('../src/cli/refero.mjs');
+}
 const [cmd, ...args] = process.argv.slice(2);
+if (fs.existsSync(fileURLToPath(new URL('../src/cli/motion.mjs', import.meta.url)))) {
+  cmds.motion = () => import('../src/cli/motion.mjs');
+}
 if (!cmds[cmd]) {
   process.stderr.write(`usage: library <${Object.keys(cmds).join('|')}> [args]\n`);
   process.exit(64);

package/entries/ada/entry.md

@@ -0,0 +1,55 @@
+---
+slug: ada
+title: 'Ada: agentic customer experience platform'
+tier: inspiration
+source:
+  kind: public-site
+  url: https://www.ada.cx/
+  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/ada-refero.mp4
+      artifacts:
+        - strip.webp
+      frames: 36
+      duration_ms: 22133
+media:
+  frames: 36
+  duration_ms: 22133
+roles: [hero, proof, feature, explainer]
+feel: [light, premium, saas, depth]
+palette:
+  canvas: '#8a7d3f'
+  ink: '#000000'
+  accent: '#0051c3'
+type:
+  display: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, "Helvetica Neue", Arial, sans-serif'
+  body: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, "Helvetica Neue", Arial, sans-serif'
+motion:
+  devices: [reveal, pan, count]
+  notes: Eyeballed from 36 sampled frames, not measured. The blurred landscape hero holds behind a live agent conversation, then reveals a logo row and proof statistics before an operating-model explainer. The metric values appear to count in, but their trigger is not visible.
+ported_from: null
+---
+
+## What it does
+
+Ada presents an agentic customer-experience platform through a live conversation, proof metrics, and operating-model explanation.
+
+## Section roster
+
+1. Hero with agent conversation card over a blurred landscape.
+2. Customer-logo proof row.
+3. AI agent performance metrics.
+4. Customer-experience operating-model explainer.
+
+## Why it works
+
+The moving landscape gives the product a more human atmosphere than a conventional software hero, while the white agent panel supplies a concrete product cue. The large background treatment can reduce contrast around the initial message.
+
+## Sources
+
+The Refero MP4 supplies the sampled motion sequence. https://www.ada.cx/ remains the source URL; its blocked live response was not retained as a capture.

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

@@ -0,0 +1,325 @@
+{
+  "url": "https://air.inc/",
+  "at": "2026-09-17",
+  "viewport": [
+    1440,
+    390
+  ],
+  "tokens": {
+    "canvas": "#13396a",
+    "ink": "#000000",
+    "accent": "#1b1b1b",
+    "fontDisplay": "\"Control Compressed\", Arial, Helvetica, sans-serif",
+    "fontBody": "Control, Arial, Helvetica, sans-serif"
+  },
+  "sections": [
+    {
+      "index": 0,
+      "tag": "header",
+      "id": "",
+      "class": "Header_root__hagAA",
+      "top": 0,
+      "height": 72,
+      "animations": []
+    },
+    {
+      "index": 1,
+      "tag": "div",
+      "id": "",
+      "class": "canvas canvas___loaded",
+      "top": 0,
+      "height": 900,
+      "animations": []
+    },
+    {
+      "index": 2,
+      "tag": "section",
+      "id": "Hero",
+      "class": "Section_root__XZMWH p-0! Section_root___spacingDefault__lCxmv",
+      "top": 0,
+      "height": 1020,
+      "animations": []
+    },
+    {
+      "index": 3,
+      "tag": "section",
+      "id": "Agentic Cards",
+      "class": "Section_root__XZMWH p-0! Section_root___spacingDefault__lCxmv bg-center bg-contain bg-no-repeat",
+      "top": 1020,
+      "height": 1021,
+      "animations": []
+    },
+    {
+      "index": 4,
+      "tag": "section",
+      "id": "",
+      "class": "flex w-full flex-col gap-12",
+      "top": 1282,
+      "height": 631,
+      "animations": []
+    },
+    {
+      "index": 5,
+      "tag": "section",
+      "id": "Logos",
+      "class": "Section_root__XZMWH Section_root___spacingSmall__u_8bU",
+      "top": 2041,
+      "height": 502,
+      "animations": []
+    },
+    {
+      "index": 6,
+      "tag": "section",
+      "id": "agent-waitlist",
+      "class": "Section_root__XZMWH p-0! Section_root___spacingDefault__lCxmv bg-center bg- bg-no-repeat",
+      "top": 2543,
+      "height": 858,
+      "animations": [
+        {
+          "target": "div.AnimatedBorder_root_stroke__5hoiG",
+          "timeline": "document",
+          "range": null,
+          "duration": 10000
+        },
+        {
+          "target": "div.AnimatedBorder_root_stroke__5hoiG",
+          "timeline": "document",
+          "range": null,
+          "duration": 10000
+        }
+      ]
+    },
+    {
+      "index": 7,
+      "tag": "section",
+      "id": "Spacing",
+      "class": "Section_root__XZMWH Section_root___spacingDefault__lCxmv bg-center bg-contain bg-no-repeat",
+      "top": 3401,
+      "height": 240,
+      "animations": []
+    },
+    {
+      "index": 8,
+      "tag": "section",
+      "id": "Supersize Text",
+      "class": "Section_root__XZMWH Section_root___spacingDefault__lCxmv",
+      "top": 3641,
+      "height": 949,
+      "animations": []
+    },
+    {
+      "index": 9,
+      "tag": "section",
+      "id": "Primary Product Demo",
+      "class": "Section_root__XZMWH p-0! Section_root___spacingDefault__lCxmv",
+      "top": 4590,
+      "height": 638,
+      "animations": []
+    },
+    {
+      "index": 10,
+      "tag": "section",
+      "id": "Features",
+      "class": "Section_root__XZMWH p-0! Section_root___spacingLarge__acfRQ",
+      "top": 5228,
+      "height": 1416,
+      "animations": [
+        {
+          "target": "div.AnimatedBorder_root_stroke__5hoiG",
+          "timeline": "document",
+          "range": null,
+          "duration": 10000
+        },
+        {
+          "target": "div.AnimatedBorder_root_stroke__5hoiG",
+          "timeline": "document",
+          "range": null,
+          "duration": 10000
+        },
+        {
+          "target": "div.AnimatedBorder_root_stroke__5hoiG",
+          "timeline": "document",
+          "range": null,
+          "duration": 10000
+        },
+        {
+          "target": "div.AnimatedBorder_root_stroke__5hoiG",
+          "timeline": "document",
+          "range": null,
+          "duration": 10000
+        },
+        {
+          "target": "div.AnimatedBorder_root_stroke__5hoiG",
+          "timeline": "document",
+          "range": null,
+          "duration": 10000
+        },
+        {
+          "target": "div.AnimatedBorder_root_stroke__5hoiG",
+          "timeline": "document",
+          "range": null,
+          "duration": 10000
+        },
+        {
+          "target": "div.AnimatedBorder_root_stroke__5hoiG",
+          "timeline": "document",
+          "range": null,
+          "duration": 10000
+        }
+      ]
+    },
+    {
+      "index": 11,
+      "tag": "section",
+      "id": "Models",
+      "class": "Section_root__XZMWH p-0! Section_root___spacingDefault__lCxmv bg-center bg-contain bg-no-repeat",
+      "top": 6645,
+      "height": 256,
+      "animations": [
+        {
+          "target": "div.CTACard_root_orbs_inner__sJJHM",
+          "timeline": "document",
+          "range": null,
+          "duration": 10000
+        },
+        {
+          "target": "div.CTACard_root_orbs_item__ocG9A",
+          "timeline": "document",
+          "range": null,
+          "duration": 6000
+        },
+        {
+          "target": "div.CTACard_root_orbs_item__ocG9A",
+          "timeline": "document",
+          "range": null,
+          "duration": 6000
+        },
+        {
+          "target": "div.CTACard_root_orbs_item__ocG9A",
+          "timeline": "document",
+          "range": null,
+          "duration": 6000
+        },
+        {
+          "target": "div.AnimatedBorder_root_stroke__5hoiG",
+          "timeline": "document",
+          "range": null,
+          "duration": 10000
+        }
+      ]
+    },
+    {
+      "index": 12,
+      "tag": "section",
+      "id": "Integrations",
+      "class": "Section_root__XZMWH Section_root___headerPadding__9L15p Section_root___spacingSmall__u_8bU bg-center bg-contain bg-no-repeat",
+      "top": 6901,
+      "height": 439,
+      "animations": []
+    },
+    {
+      "index": 13,
+      "tag": "section",
+      "id": "Storytelling",
+      "class": "Section_root__XZMWH Section_root___spacingDefault__lCxmv bg-center bg-contain bg-no-repeat",
+      "top": 7340,
+      "height": 3888,
+      "animations": []
+    },
+    {
+      "index": 14,
+      "tag": "section",
+      "id": "Book a Demo Form",
+      "class": "Section_root__XZMWH Section_root___spacingDefault__lCxmv",
+      "top": 11228,
+      "height": 1162,
+      "animations": [
+        {
+          "target": "h1.u-h2-large",
+          "timeline": "document",
+          "range": null,
+          "duration": 1000
+        },
+        {
+          "target": "h1.u-h2-large",
+          "timeline": "document",
+          "range": null,
+          "duration": 1000
+        },
+        {
+          "target": "span",
+          "timeline": "document",
+          "range": null,
+          "duration": 1000
+        },
+        {
+          "target": "span",
+          "timeline": "document",
+          "range": null,
+          "duration": 1000
+        },
+        {
+          "target": "span",
+          "timeline": "document",
+          "range": null,
+          "duration": 1000
+        },
+        {
+          "target": "span",
+          "timeline": "document",
+          "range": null,
+          "duration": 1000
+        },
+        {
+          "target": "span",
+          "timeline": "document",
+          "range": null,
+          "duration": 1000
+        },
+        {
+          "target": "span",
+          "timeline": "document",
+          "range": null,
+          "duration": 1000
+        },
+        {
+          "target": "span",
+          "timeline": "document",
+          "range": null,
+          "duration": 1000
+        },
+        {
+          "target": "span",
+          "timeline": "document",
+          "range": null,
+          "duration": 1000
+        },
+        {
+          "target": "p",
+          "timeline": "document",
+          "range": null,
+          "duration": 1000
+        },
+        {
+          "target": "p",
+          "timeline": "document",
+          "range": null,
+          "duration": 1000
+        }
+      ]
+    },
+    {
+      "index": 15,
+      "tag": "footer",
+      "id": "Footer",
+      "class": "Section_root__XZMWH p-0! Footer_root__g9BuT",
+      "top": 12390,
+      "height": 1350,
+      "animations": []
+    }
+  ],
+  "screenshots": {
+    "390": "screen-390.png",
+    "1440": "screen-1440.png"
+  }
+}

package/entries/air/entry.md

@@ -0,0 +1,62 @@
+---
+slug: air
+title: 'Air: visual asset workspace'
+tier: inspiration
+source:
+  kind: public-site
+  url: https://air.inc/
+  license: Captured from a Refero-hosted recording and the live site; description only, no redistribution of the source.
+captured:
+  method: both
+  at: '2026-09-17'
+  tool: wp-design-library@0.4.0
+  captures:
+    - method: frames
+      input: /tmp/air-refero.mp4
+      artifacts:
+        - strip.webp
+      frames: 36
+      duration_ms: 29583
+    - method: both
+      input: https://air.inc/
+      artifacts:
+        - captures/2/strip.webp
+        - captures/2/measure.json
+        - captures/2/screen-1440.png
+        - captures/2/screen-390.png
+media:
+  frames: 36
+  duration_ms: 29583
+roles: [hero, explainer, capability, feature, proof]
+feel: [light, premium, playful, saas, depth]
+palette:
+  canvas: '#13396a'
+  ink: '#000000'
+  accent: '#1b1b1b'
+type:
+  display: '"Control Compressed", Arial, Helvetica, sans-serif'
+  body: Control, Arial, Helvetica, sans-serif
+motion:
+  devices: [reveal, pan, parallax, drift]
+  notes: Eyeballed from 36 sampled frames, not measured. The blue-sky hero gives way to floating asset cards, workspace views, and large statement transitions as the recording moves downward. Cards drift independently over the background; individual triggers are not visible.
+ported_from: null
+---
+
+## What it does
+
+Air presents a visual workspace for collecting, organizing, and collaborating around creative assets.
+
+## Section roster
+
+1. Sky-toned hero and product promise.
+2. Asset-card and workspace demonstration.
+3. Large organizing statement with content examples.
+4. Collaboration and library capability scenes.
+
+## Why it works
+
+The airy background gives a dense creative tool room to breathe, while the moving cards make the organizing promise visible. The page relies on a long visual sequence, so its supporting explanation is easy to skim past.
+
+## Sources
+
+The Refero MP4 supplies the sampled motion sequence. The live capture at https://air.inc/ supplies the current site URL and layout reference.