@yojahny/wp-design-library 0.1.0

package/src/mcp/prompts.mjs

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+
+// The add-entry prompt is the authoring command. Claude Code surfaces it as a slash
+// command (/mcp__wp-design-library__add-entry) in any session with this server
+// registered, so the plugin that consumes the library never has to ship it.
+// The vocabulary is rendered from ctx.vocab at call time: no copy can drift.
+
+function list(set) { return [...set].join(', '); }
+
+export function addEntryPrompt(ctx, a) {
+  const v = ctx.vocab.facets;
+  const aliases = [...ctx.vocab.aliases.entries()].map(([alias, canon]) => `\`${alias}\` → \`${canon}\``).join(', ');
+  const given = Object.entries(a).filter(([, val]) => val).map(([k, val]) => `- ${k}: ${val}`).join('\n');
+  return `# Add a design reference to wp-design-library
+
+Arguments given:
+${given || '- (none)'}
+
+The server does the mechanical half: it samples frames into \`strip.png\` 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.
+
+## Order of operations
+
+1. **Arguments.** \`path\` must exist; pass it as an absolute path. Animated webp and gif
+   always work; video (mp4/mov/webm/mkv) needs ffmpeg on the server's PATH. If \`add\`
+   returns \`refused\` starting with \`ffmpeg\`, relay the message and stop. \`source\` is
+   one of ${list(v.source)}. Derive \`slug\` from the file name when absent (lowercase,
+   dashes, no extension) and confirm it with the user; derive \`title\` from the slug and
+   confirm. \`url\` must be a full URL with scheme. \`license\` defaults by kind: own →
+   "own work"; open → ask for the licence name; paid and public-site → "description
+   only, no redistribution of the source".
+2. **Ingest.** Call the \`add\` tool with those values. If it returns \`refused\` because
+   the slug exists, ask before calling again with \`force: true\`; a forced re-add resets
+   the draft. Over a hosted (HTTP) server \`add\` can only read files already in the server's
+   inbox; if the refusal mentions \`inbox\`, say so and stop.
+3. **Read.** Open the returned \`strip\`. Read \`media.duration_ms\` from the draft at
+   \`<dir>/entry.md\`; if it is above 10000, call \`add\` again with \`force: true\` and
+   \`frames: 36\` before tagging. The server caps at 36 frames; beyond about 18 seconds a
+   section can still be missed, so build a denser sheet yourself from the source file
+   before writing the motion note.
+4. **Tag.** Fill every field in the returned \`blanks\` list in \`<dir>/entry.md\`, per the
+   rubric below. Write the motion note last, after the roster.
+5. **Approve.** Show the draft to the user and **show the draft and wait for a yes** before
+   anything else. Apply their edits.
+6. **Save.** Call \`save_entry\`. On \`refused\`, show the field names, fix, and call again;
+   **never remove a field to make it pass**.
+7. **Offer the git step.** The library checkout is the directory that contains the
+   \`bin/library.mjs\` this server runs; if that is not a git checkout (the \`npx\` case), ask
+   the user for the path to their clone. If the \`dir\` returned by \`add\` is not inside the
+   checkout, first \`cp -r <dir> <checkout>/entries/\`. Then, only with \`git -C <checkout>\`
+   and never in the current project: \`checkout -B content/<slug> main\`, \`add
+   entries/<slug>\`, commit \`content: <title>\`, \`push -u origin content/<slug>\`, and
+   \`env -u GH_TOKEN gh pr create --repo yojahny55/wp-design-library --head content/<slug>
+   --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.
+
+## Tagging rubric
+
+Read the whole page before tagging any section: roster first, then feel, then motion.
+
+| Field | Write |
+|---|---|
+| \`roles\` | every page section, in order, from: ${list(v.role)} |
+| \`feel\` | three to six of: ${list(v.feel)} |
+| \`palette.canvas/ink/accent\` | three hex values eyeballed from the strip |
+| \`type.display\`, \`type.body\` | family feel, weight, tracking, in words; never a font name you did not see |
+| \`motion.devices\` | only what was seen, from: ${list(v.motion)} |
+| \`motion.notes\` | one paragraph, per section in page order: what moves, relative to what, how it hands off. Begin with "Eyeballed from N sampled frames, not measured." Name what you could not tell. |
+| body | three headed sections: \`## What it does\`, \`## Section roster\`, \`## Why it works\`; the last ends with the cost to weigh |
+
+Aliases resolve on save: ${aliases}. Any other term is refused with the facet and term
+named. Do not invent a term; if the pattern is real and unnamed, describe it in
+\`motion.notes\` and propose the term to the operator.
+A term is **added by a PR to \`vocab.yaml\`, never by an ingest**.
+
+Licence kinds: \`own\` and \`open\` may later gain a \`ported/\` folder of real code; \`paid\`
+and \`public-site\` are inspiration only and \`save_entry\` refuses \`tier: ported\` on them.
+
+## Never
+
+- Never fill a field with a value you did not read off the strip.
+- Never call \`save_entry\` before the user has seen the draft.
+- Never run git in the current project.`;
+}
+
+// brief-from-library turns a client brief into a search plan: one `search` call per
+// role the page needs, feel filters from the brief's own vibe words, then a
+// `## References` block the session fills in with the slugs it actually used.
+
+export function briefFromLibraryPrompt(ctx, { brief }) {
+  const v = ctx.vocab.facets;
+  const roles = list(v.role);
+  const feels = list(v.feel);
+  return `# Build a brief from the design library
+
+Brief given:
+
+${brief}
+
+## What to do
+
+For each of the ${v.role.size} roles below, call the \`search\` tool once with \`filters.role\`
+set to that role, \`limit: 3\`, and \`filters.feel\` set to whichever feel terms from
+the vocabulary (${feels}) match the brief's own vibe words. Roles: ${roles}.
+
+Read the results, pick the entries that best fit the brief for each role, and use
+\`get_entry\` on any slug whose body you need to see in full before deciding.
+
+A hit whose \`ranks.fts\` is null is a weak, vector-only match: it matched by semantic
+distance alone, not by any keyword in the query. If a role's results are all weak,
+report that role as having no reference rather than filling it with a weak match.
+
+## Output
+
+End your reply with a \`## References\` block: one line per slug you actually used,
+each line starting with the slug (e.g. \`ais-community-dark-depth: hero, dark bed
+with slower parallax\`).`;
+}
+
+export function registerPrompts(server, ctx) {
+  server.registerPrompt(
+    'brief-from-library',
+    {
+      description: "Turn a client brief into a search plan against this library: one search per role, feel filters from the brief's vibe words, and a References block of the slugs used.",
+      argsSchema: { brief: z.string().describe('the client brief or page description to search the library against') },
+    },
+    async (a) => ({ messages: [{ role: 'user', content: { type: 'text', text: briefFromLibraryPrompt(ctx, a) } }] }),
+  );
+
+  server.registerPrompt(
+    'add-entry',
+    {
+      description: 'Add a design reference to the library: ingest a recording, tag it in this session per the rubric, approve the draft, save it, offer the PR.',
+      argsSchema: {
+        path: z.string().describe('absolute path to an animated webp/gif or a video file'),
+        source: z.string().describe('own | open | paid | public-site'),
+        slug: z.string().optional().describe('lowercase, digits and dashes'),
+        title: z.string().optional(),
+        url: z.string().optional().describe('where it came from, full URL'),
+        license: z.string().optional(),
+      },
+    },
+    async (a) => ({ messages: [{ role: 'user', content: { type: 'text', text: addEntryPrompt(ctx, a) } }] }),
+  );
+}

package/src/mcp/resources.mjs

@@ -0,0 +1,24 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+export function registerResources(server, ctx) {
+  server.registerResource(
+    'vocab',
+    'library://vocab',
+    { title: 'Vocabulary', description: 'The facet vocabulary (roles, feel, motion, source, tier) as declared in vocab.yaml.', mimeType: 'text/yaml' },
+    async (uri) => ({ contents: [{ uri: uri.href, mimeType: 'text/yaml', text: fs.readFileSync(ctx.paths.vocab, 'utf8') }] }),
+  );
+
+  server.registerResource(
+    'entry',
+    new ResourceTemplate('library://entry/{slug}', { list: undefined }),
+    { title: 'Entry', description: "One entry's entry.md, frontmatter and prose body.", mimeType: 'text/markdown' },
+    async (uri, { slug }) => {
+      if (!/^[a-z0-9-]+$/.test(slug)) throw new Error('no entry ' + slug);
+      const file = path.join(ctx.paths.entries, slug, 'entry.md');
+      if (!fs.existsSync(file)) throw new Error('no entry ' + slug);
+      return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text: fs.readFileSync(file, 'utf8') }] };
+    },
+  );
+}

package/src/mcp/server.mjs

@@ -0,0 +1,28 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { paths } from '../paths.mjs';
+import { loadVocab } from '../vocab.mjs';
+import { getEmbedder } from '../index/embed.mjs';
+import { registerPrompts } from './prompts.mjs';
+import { registerResources } from './resources.mjs';
+import { makeTools, registerTools } from './tools.mjs';
+
+export async function buildServer(opts = {}) {
+  const transport = opts.transport ?? 'stdio';
+  const p = paths();
+  const ctx = { paths: p, vocab: loadVocab(p.vocab), transport, models: p.models };
+  // http passes its own cached embedder in (one per process, not one per request); stdio resolves its own.
+  ctx.embedder = 'embedder' in opts ? opts.embedder : await getEmbedder({ models: ctx.models });
+  const server = new McpServer({ name: 'wp-design-library', version: p.version });
+  registerTools(server, makeTools(ctx));
+  registerPrompts(server, ctx);
+  registerResources(server, ctx);
+  return server;
+}
+
+export async function serveStdio() {
+  const server = await buildServer();
+  const log = (...a) => process.stderr.write(a.join(' ') + '\n');
+  await server.connect(new StdioServerTransport());
+  log('wp-design-library: stdio ready');
+}

package/src/mcp/tools.mjs

@@ -0,0 +1,152 @@
+import fs from 'node:fs';
+import path from 'node:path';
+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';
+
+const facetList = z.array(z.string()).optional();
+const FILTER_FACETS = ['role', 'feel', 'motion', 'source'];
+
+// Aliases resolve on query (spec §5): map each filter term to its canonical
+// vocab term. A term that resolves to nothing is dropped from the filter and
+// reported back so the caller knows why a filter had no effect.
+function resolveFilters(vocab, filters = {}) {
+  const resolved = {};
+  const unknown = [];
+  for (const facet of FILTER_FACETS) {
+    const terms = filters[facet];
+    if (!terms) continue;
+    const ok = [];
+    for (const term of terms) {
+      const canon = resolveTerm(vocab, facet, term);
+      if (canon === null) unknown.push({ facet, term });
+      else ok.push(canon);
+    }
+    if (ok.length) resolved[facet] = ok;
+  }
+  if (filters.tier !== undefined) {
+    const canon = resolveTerm(vocab, 'tier', filters.tier);
+    if (canon === null) unknown.push({ facet: 'tier', term: filters.tier });
+    else resolved.tier = canon;
+  }
+  return { filters: resolved, unknown };
+}
+
+// Over http, a path argument names a file the server reads on the caller's
+// behalf; an untrusted remote caller could otherwise name any file readable
+// by the process. Confine it to the drop folder. Stdio has no such caller
+// (the operator running the CLI already has that file access), so it stays
+// unrestricted there. Shared by `add` (input) and `similar` (image).
+function confineToInbox(ctx, inputPath) {
+  if (ctx.transport !== 'http') return null;
+  // Realpath the inbox root itself (when it exists) so a symlinked <data>/inbox still
+  // confines correctly: inputPath's own realpath resolves through that symlink too, and
+  // comparing against the unresolved join would then never match.
+  let inboxRoot = path.join(ctx.paths.data, 'inbox');
+  if (fs.existsSync(inboxRoot)) inboxRoot = fs.realpathSync(inboxRoot);
+  const inbox = inboxRoot + path.sep;
+  // existsSync is false for a dangling symlink too, not just a missing path: refuse
+  // both explicitly instead of falling through to path.resolve, which would let a
+  // dangling symlink under inbox pass confinement on its unresolved path alone.
+  if (!fs.existsSync(inputPath)) return 'input does not exist';
+  const real = fs.realpathSync(inputPath);
+  return real.startsWith(inbox) ? null : 'over http, the path must be a file under <data>/inbox';
+}
+
+export function makeTools(ctx) {
+  const withDb = (fn) => async (args) => {
+    const db = openIndex(ctx.paths.index);
+    try { return await fn(db, args); } finally { db.close(); }
+  };
+  return [
+    {
+      name: 'search',
+      description: 'Search design references by keyword and facet filters, fused by reciprocal rank fusion when the vector arm is available. Returns slugs ranked by score; arms lists which retrieval arms ran. A hit whose ranks.fts is null is a weak, vector-only match: it matched by semantic distance alone, not by any keyword in the query.',
+      schema: z.object({
+        query: z.string().default(''),
+        filters: z.object({ role: facetList, feel: facetList, motion: facetList, source: facetList, tier: z.string().optional() }).optional(),
+        limit: z.number().int().min(1).max(50).default(10),
+      }),
+      handler: withDb(async (db, a) => {
+        const { filters, unknown } = resolveFilters(ctx.vocab, a.filters ?? {});
+        const result = await search(db, { ...a, filters, embedder: ctx.embedder });
+        return unknown.length ? { ...result, unknown } : result;
+      }),
+    },
+    {
+      name: 'get_entry',
+      description: 'Return one entry: frontmatter, prose body, and the path to its strip.png.',
+      schema: z.object({ slug: z.string() }),
+      handler: withDb((db, { slug }) => {
+        const e = getEntry(db, slug);
+        return e ? { ...e, strip: `${e.dir}/strip.png` } : { refused: `no entry with slug ${slug}` };
+      }),
+    },
+    {
+      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.",
+      schema: z.object({
+        slug: z.string().optional(),
+        image: z.string().optional(),
+        limit: z.number().int().min(1).max(50).default(10),
+      }),
+      handler: withDb(async (db, a) => {
+        if (!!a.slug === !!a.image) return { refused: 'similar needs exactly one of slug or image' };
+        if (a.image) {
+          const refusal = confineToInbox(ctx, a.image);
+          if (refusal) return { refused: refusal };
+        }
+        return similar(db, { ...a, embedder: ctx.embedder });
+      }),
+    },
+    {
+      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.',
+      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),
+      }),
+      handler: async (a) => {
+        // A URL is fetched over the network by Chrome, not read off disk on the
+        // caller's behalf, so the inbox confinement (local file paths only) doesn't
+        // apply to it; a bare local path still does.
+        if (/^https?:\/\//.test(a.input)) {
+          const refusal = await refuseUnsafeUrl(a.input, { transport: ctx.transport });
+          if (refusal) return { refused: refusal };
+        } else {
+          const refusal = confineToInbox(ctx, a.input);
+          if (refusal) return { refused: refusal };
+        }
+        return (await import('../cli/add.mjs')).addEntry(a);
+      },
+    },
+    {
+      name: 'refresh',
+      description: 'Re-measure a drafted URL entry (source.url set, captured.method measured|both) with the system Chrome: rewrites measure.json, bumps captured.at, and reindexes. Refuses an entry with no URL or one drafted from frames only.',
+      schema: z.object({ slug: z.string().regex(/^[a-z0-9-]+$/) }),
+      handler: async ({ slug }) => (await import('../cli/refresh.mjs')).refreshEntry({ slug, transport: ctx.transport }),
+    },
+    {
+      name: 'save_entry',
+      description: 'Validate a filled draft against the vocabulary and licence gate, then reindex. Refuses with the field names on any blank or unknown term.',
+      schema: z.object({ slug: z.string().regex(/^[a-z0-9-]+$/) }),
+      handler: async ({ slug }) => {
+        const { saveEntry } = await import('../ingest/save.mjs');
+        return saveEntry({ dir: path.join(ctx.paths.entries, slug), vocab: ctx.vocab, indexPath: ctx.paths.index, entriesDir: ctx.paths.entries, models: ctx.paths.models });
+      },
+    },
+  ];
+}
+
+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 };
+    });
+  }
+}

package/src/paths.mjs

@@ -0,0 +1,21 @@
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const VERSION = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version;
+
+export function paths(env = process.env) {
+  const data = env.LIBRARY_DATA ? path.resolve(env.LIBRARY_DATA) : ROOT;
+  return {
+    root: ROOT,
+    data,
+    entries: path.join(data, 'entries'),
+    // Entries shipped with the code (the image). Synced into `entries` on every start.
+    seed: env.LIBRARY_SEED ? path.resolve(env.LIBRARY_SEED) : path.join(ROOT, 'entries'),
+    index: path.join(data, '.library', 'index.sqlite'),
+    vocab: path.join(ROOT, 'vocab.yaml'),
+    models: env.LIBRARY_MODELS ? path.resolve(env.LIBRARY_MODELS) : path.join(data, 'models'),
+    version: VERSION,
+  };
+}

package/src/ui/app.js

@@ -0,0 +1,34 @@
+// Vanilla, no build step: filters the manifest already rendered into `.card`
+// data attributes. Within one facet, checked boxes OR together; across facets, AND.
+(function () {
+  var grid = document.getElementById('grid');
+  var cards = grid ? Array.prototype.slice.call(grid.querySelectorAll('.card')) : [];
+  var facets = ['role', 'feel', 'motion', 'source', 'tier'];
+  var draftsToggle = document.getElementById('drafts-toggle');
+
+  function selected(facet) {
+    var boxes = document.querySelectorAll('input[name="' + facet + '"]:checked');
+    return Array.prototype.map.call(boxes, function (b) { return b.value; });
+  }
+
+  function apply() {
+    var active = {};
+    for (var i = 0; i < facets.length; i++) active[facets[i]] = selected(facets[i]);
+    var showDrafts = !!(draftsToggle && draftsToggle.checked);
+    cards.forEach(function (card) {
+      var isDraft = card.dataset.draft === 'true';
+      var ok = showDrafts || !isDraft;
+      for (var i = 0; ok && i < facets.length; i++) {
+        var want = active[facets[i]];
+        if (!want.length) continue;
+        var have = (card.dataset[facets[i]] || '').split(' ');
+        ok = want.some(function (t) { return have.indexOf(t) !== -1; });
+      }
+      card.hidden = !ok;
+    });
+  }
+
+  var inputs = document.querySelectorAll('#filters input[type="checkbox"]');
+  Array.prototype.forEach.call(inputs, function (input) { input.addEventListener('change', apply); });
+  apply();
+})();

package/src/ui/build.mjs

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { listEntries, parseEntry, validateEntry } from '../entry.mjs';
+import { loadVocab, FACETS } from '../vocab.mjs';
+
+const DIR = path.dirname(fileURLToPath(import.meta.url));
+const TPL = path.join(DIR, 'templates');
+
+function esc(s) {
+  return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+function render(tpl, vars) {
+  return tpl.replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k] ?? '');
+}
+
+// The 20-line converter: headings, paragraphs, fenced code. Text is always escaped.
+function mdToHtml(md) {
+  const out = [];
+  let para = [], code = null;
+  const flush = () => { if (para.length) { out.push(`<p>${esc(para.join(' '))}</p>`); para = []; } };
+  for (const line of md.split('\n')) {
+    if (line.trim().startsWith('```')) {
+      if (code) { out.push(`<pre><code>${code.join('\n')}</code></pre>`); code = null; } else { flush(); code = []; }
+      continue;
+    }
+    if (code) { code.push(esc(line)); continue; }
+    const h = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (h) { flush(); out.push(`<h${h[1].length}>${esc(h[2])}</h${h[1].length}>`); continue; }
+    if (!line.trim()) { flush(); continue; }
+    para.push(line.trim());
+  }
+  flush();
+  return out.join('\n');
+}
+
+function filterFieldset(facet, terms) {
+  const legend = facet.charAt(0).toUpperCase() + facet.slice(1);
+  const boxes = [...terms].sort().map((t) => `<label><input type="checkbox" name="${facet}" value="${esc(t)}"> ${esc(t)}</label>`).join(' ');
+  return `<fieldset><legend>${legend}</legend>${boxes}</fieldset>`;
+}
+
+function card(row) {
+  const img = row.strip ? `<img src="${row.strip}" alt="">` : `<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(' '))}"`;
+  return `<a class="card" href="entry/${esc(row.slug)}.html" ${data} data-source="${esc(row.source)}" data-tier="${esc(row.tier)}" data-draft="${row.draft}">` +
+    `${img}<div class="meta"><strong>${esc(row.title)}</strong>${badge}<br><small>${esc(row.tier)} &middot; ${tags}</small></div></a>`;
+}
+
+// measure.json is only written for a live-URL capture (`add <url>`/`refresh`); frame-sampled entries have none.
+function measurementsHtml(dir) {
+  const file = path.join(dir, 'measure.json');
+  if (!fs.existsSync(file)) return '';
+  const m = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const t = m.tokens ?? {};
+  return `<h2>Measured tokens</h2><dl><dt>Canvas</dt><dd>${esc(t.canvas)}</dd><dt>Ink</dt><dd>${esc(t.ink)}</dd><dt>Accent</dt><dd>${esc(t.accent)}</dd></dl>` +
+    `<p>${(m.sections ?? []).length} sections measured.</p>`;
+}
+
+function writeEntryPage(outDir, entry, row) {
+  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(', ')),
+    MOTION: esc(row.motion.join(', ')), SOURCE: esc(row.source), LICENSE: esc(entry.fm.source?.license),
+    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),
+  });
+  fs.writeFileSync(path.join(outDir, 'entry', `${row.slug}.html`), html);
+}
+
+// `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 }) {
+  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 });
+
+  const rows = [];
+  for (const dir of listEntries(entriesDir)) {
+    let entry;
+    try { entry = parseEntry(dir); } catch (err) { process.stderr.write(`ui: skipping ${path.basename(dir)}: ${err.message}\n`); continue; }
+    const { ok } = validateEntry(entry, vocab);
+    // Filesystem paths and URLs are always derived from the directory name, never from
+    // frontmatter fm.slug: a draft (failing validateEntry) is not forced to have
+    // 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 hasStrip = fs.existsSync(stripSrc);
+    if (hasStrip) fs.copyFileSync(stripSrc, path.join(outDir, 'strips', `${slug}.png`));
+    const fm = entry.fm;
+    const capturedAt = fm.captured?.at;
+    const captured = capturedAt instanceof Date ? capturedAt.toISOString().slice(0, 10) : String(capturedAt ?? '');
+    // fm.slug is never a path, so an untitled draft may still fall back to it as display
+    // text — esc() (card()/writeEntryPage()) is what makes that safe, not the dir-based slug.
+    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,
+    };
+    rows.push(row);
+    writeEntryPage(outDir, entry, row);
+  }
+  rows.sort((a, b) => b.captured.localeCompare(a.captured));
+
+  fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify(rows, null, 2));
+  const tpl = fs.readFileSync(path.join(TPL, 'index.html'), 'utf8');
+  const filters = FACETS.map((f) => filterFieldset(f, vocab.facets[f])).join('\n');
+  fs.writeFileSync(path.join(outDir, 'index.html'), render(tpl, { FILTERS: filters, GRID: rows.map(card).join('\n') }));
+  fs.copyFileSync(path.join(DIR, 'app.js'), path.join(outDir, 'app.js'));
+
+  const drafts = rows.filter((r) => r.draft).length;
+  return { entries: rows.length - drafts, drafts };
+}

package/src/ui/serve.mjs

@@ -0,0 +1,38 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+};
+
+// Serves one file under `root`. Takes the raw request-target (`req.url`, or the
+// pathname component of it) rather than a WHATWG `URL#pathname` — that parser folds
+// `%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) {
+  const pathname = rawPath.split('?')[0];
+  let rel;
+  try { rel = decodeURIComponent(pathname); } catch { res.writeHead(404); return res.end(); }
+  if (rel === '/') rel = '/index.html';
+  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);
+}
+
+// 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);
+  });
+  await new Promise((resolve, reject) => { srv.once('error', reject); srv.listen(port, resolve); });
+  process.stderr.write(`wp-design-library: ui on :${port}\n`);
+  return new Promise(() => {}); // stay alive until killed
+}

package/src/ui/templates/entry.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>{{TITLE}}</title>
+<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; }
+  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; }
+</style>
+</head>
+<body>
+<p><a href="../index.html">&larr; back to the gallery</a></p>
+<h1>{{TITLE}} {{DRAFT_BADGE}}</h1>
+{{STRIP_IMG}}
+<dl>
+<dt>Tier</dt><dd>{{TIER}}</dd>
+<dt>Roles</dt><dd>{{ROLES}}</dd>
+<dt>Feel</dt><dd>{{FEEL}}</dd>
+<dt>Motion</dt><dd>{{MOTION}}</dd>
+<dt>Source</dt><dd>{{SOURCE}}</dd>
+<dt>Licence</dt><dd>{{LICENSE}}</dd>
+<dt>Captured</dt><dd>{{CAPTURED}}</dd>
+</dl>
+{{MEASUREMENTS}}
+{{BODY}}
+</body>
+</html>

package/src/ui/templates/index.html

@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>wp-design-library</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>
+  :root { color-scheme: dark light; }
+  body { font: 14px/1.4 system-ui, sans-serif; margin: 0; padding: 1rem; }
+  fieldset { display: inline-block; margin: 0 .5rem .5rem 0; border-radius: 6px; }
+  #filters { margin-bottom: 1rem; }
+  #grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(220px, 1fr)); gap: 1rem; }
+  .card { border: 1px solid #8883; border-radius: 8px; overflow: hidden; color: inherit; text-decoration: none; display: block; }
+  .card img { width: 100%; display: block; aspect-ratio: 4/3; object-fit: cover; background: #8882; }
+  .card .ph { width: 100%; aspect-ratio: 4/3; background: #8882; }
+  .card .meta { padding: .5rem; }
+  .badge { background: #d33; color: #fff; font-size: .7em; padding: .1em .4em; border-radius: 4px; }
+  [hidden] { display: none !important; }
+</style>
+</head>
+<body>
+<h1>wp-design-library</h1>
+<form id="filters">
+{{FILTERS}}
+<label><input type="checkbox" id="drafts-toggle"> Show drafts</label>
+</form>
+<div id="grid">
+{{GRID}}
+</div>
+<script src="app.js"></script>
+</body>
+</html>