@yojahny/wp-design-library 0.1.0

package/src/cli/add.mjs

@@ -0,0 +1,163 @@
+import path from 'node:path';
+import sharp from 'sharp';
+import { paths } from '../paths.mjs';
+import { sampleFrames, compositeStrip } from '../ingest/frames.mjs';
+import { writeDraft } from '../ingest/draft.mjs';
+import { measure } from '../ingest/measure.mjs';
+import { loadVocab, resolveTerm } from '../vocab.mjs';
+
+function opt(args, name) { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; }
+
+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
+// does for video/animated-image input.
+async function stripFromFrames(framePaths, outPng) {
+  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);
+}
+
+// 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 }) {
+  const fs = await import('node:fs');
+  const os = await import('node:os');
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'wpdl-add-'));
+  let result;
+  try {
+    result = await measure(input, scratch, { record });
+  } catch (err) {
+    fs.rmSync(scratch, { recursive: true, force: true });
+    throw err;
+  }
+  if (!result.ok && !result.frames?.length) {
+    fs.rmSync(scratch, { recursive: true, force: true });
+    return { refused: result.error };
+  }
+
+  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');
+  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));
+    }
+  } 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);
+  }
+  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 });
+  return { dir: d.dir, strip, blanks: d.blanks, measured: result.ok };
+}
+
+export async function addEntry({ input, slug, title, source, force = false, frames, record = 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
+  // both `add` and `--inbox` route through, since addInbox calls addEntry per file.
+  if (resolveTerm(loadVocab(p.vocab), 'source', source.kind) === null) {
+    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 os = await import('node:os');
+  if (existsSync(path.join(dir, 'entry.md')) && !force) {
+    return { refused: `entry ${slug} exists; pass force to overwrite` };
+  }
+  if (URL_RE.test(input)) {
+    return addFromUrl({ p, input, slug, title, source, dir, record });
+  }
+  // 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');
+  let media;
+  try {
+    media = await sampleFrames(input, scratchStrip, { frames });
+  } catch (err) {
+    rmSync(scratch, { recursive: true, force: true });
+    if (err.message?.startsWith('ffmpeg')) return { refused: err.message };
+    throw err;
+  }
+  mkdirSync(dir, { recursive: true });
+  const strip = path.join(dir, 'strip.png');
+  try {
+    renameSync(scratchStrip, strip);
+  } catch {
+    copyFileSync(scratchStrip, strip);
+    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 });
+  return { dir: d.dir, strip, blanks: d.blanks, frames: media.frames };
+}
+
+export async function addInbox({ source }) {
+  const p = paths();
+  const fs = await import('node:fs');
+  const inbox = path.join(p.data, 'inbox');
+  const out = [];
+  if (!fs.existsSync(inbox)) return out;
+  const seenSlugs = new Map(); // ponytail: slug -> first file this run, names the collision
+  for (const file of fs.readdirSync(inbox).filter((f) => MEDIA.test(f)).sort()) {
+    const slug = slugify(file);
+    if (!slug) { out.push({ file, slug, status: 'refused', reason: 'cannot derive a slug from the file name; pass --slug' }); continue; }
+    if (seenSlugs.has(slug)) { out.push({ file, slug, status: 'refused', reason: `slug ${slug} collides with ${seenSlugs.get(slug)} in this run` }); continue; }
+    seenSlugs.set(slug, file);
+    const full = path.join(inbox, file);
+    if (fs.existsSync(path.join(p.entries, slug, 'entry.md'))) { out.push({ file, slug, status: 'skipped', reason: 'entry exists' }); continue; }
+    let meta = {};
+    const side = full + '.json';
+    if (fs.existsSync(side)) { try { meta = JSON.parse(fs.readFileSync(side, 'utf8')); } catch (e) { out.push({ file, slug, status: 'refused', reason: 'sidecar is not JSON' }); continue; } }
+    if (meta === null || typeof meta !== 'object' || Array.isArray(meta)) { out.push({ file, slug, status: 'refused', reason: 'sidecar must be a JSON object' }); continue; }
+    const kind = meta.kind ?? source?.kind, license = meta.license ?? source?.license;
+    if (!kind || !license) { out.push({ file, slug, status: 'refused', reason: 'no source kind/license: add a <file>.json sidecar or pass --source and --license' }); continue; }
+    try {
+      const r = await addEntry({ input: full, slug, title: meta.title ?? slug.replace(/-/g, ' '), source: { kind, url: meta.url ?? source?.url, license } });
+      out.push(r.refused ? { file, slug, status: 'refused', reason: r.refused } : { file, slug, status: 'drafted', frames: r.frames });
+    } catch (e) { out.push({ file, slug, status: 'refused', reason: e.message }); }
+  }
+  return out;
+}
+
+export async function run(args) {
+  if (args.includes('--inbox')) {
+    const out = await addInbox({ source: { kind: opt(args, '--source'), url: opt(args, '--url'), license: opt(args, '--license') } });
+    for (const line of out) process.stdout.write(JSON.stringify(line) + '\n');
+    return out.some((l) => l.status === 'refused') ? 1 : 0;
+  }
+  const framesRaw = opt(args, '--frames');
+  let frames;
+  if (framesRaw !== undefined) {
+    frames = Number(framesRaw);
+    if (!Number.isInteger(frames) || frames < 6 || frames > 36) {
+      process.stdout.write(JSON.stringify({ refused: '--frames must be an integer between 6 and 36' }) + '\n');
+      return 1;
+    }
+  }
+  const out = await addEntry({
+    input: args[0], slug: opt(args, '--slug'), title: opt(args, '--title'),
+    source: { kind: opt(args, '--source'), url: opt(args, '--url'), license: opt(args, '--license') },
+    force: args.includes('--force'),
+    frames,
+    record: args.includes('--record'),
+  });
+  process.stdout.write(JSON.stringify(out) + '\n');
+  return out.refused ? 1 : 0;
+}

package/src/cli/check.mjs

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import { paths } from '../paths.mjs';
+import { loadVocab } from '../vocab.mjs';
+import { listEntries, parseEntry, validateEntry } from '../entry.mjs';
+import { fetchModels, modelDirs } from '../index/embed.mjs';
+
+export async function run(args = []) {
+  const p = paths();
+  if (args.includes('--fetch-models')) {
+    await fetchModels(p.models);
+    const d = modelDirs(p.models);
+    process.stdout.write(`model: ${d.text}\nmodel: ${d.image}\n`);
+    return 0;
+  }
+  const vocab = loadVocab(p.vocab);
+  let bad = 0, n = 0;
+  for (const dir of listEntries(p.entries)) {
+    n++;
+    let e;
+    try { e = parseEntry(dir); } catch (err) { bad++; process.stderr.write(`${path.basename(dir)}: ${err.message}\n`); continue; }
+    const r = validateEntry(e, vocab);
+    if (!r.ok) { bad++; for (const m of r.errors) process.stderr.write(`${e.slug}: ${m}\n`); }
+  }
+  process.stdout.write(`${n - bad}/${n} entries ok\n`);
+  return bad ? 1 : 0;
+}

package/src/cli/export.mjs

@@ -0,0 +1,41 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { paths } from '../paths.mjs';
+import { listEntries, parseEntry, validateEntry } from '../entry.mjs';
+import { loadVocab } from '../vocab.mjs';
+
+export async function run(args = []) {
+  const p = paths();
+  if (!fs.existsSync(p.entries)) { process.stderr.write('export: no entries directory\n'); return 1; }
+  const base = path.basename(p.entries);
+  let dirs = listEntries(p.entries);
+  let targets = [base];
+  if (args.includes('--saved-only')) {
+    const vocab = loadVocab(p.vocab);
+    let skipped = 0;
+    dirs = dirs.filter((dir) => {
+      let ok;
+      try { ok = validateEntry(parseEntry(dir), vocab).ok; } catch { ok = false; }
+      if (!ok) skipped++;
+      return ok;
+    });
+    targets = dirs.map((dir) => path.join(base, path.basename(dir)));
+    process.stderr.write(`skipped ${skipped} drafts\n`);
+    if (targets.length === 0) { process.stderr.write('export: no saved entries to export\n'); return 1; }
+  }
+  const n = dirs.length;
+  let tar;
+  try {
+    // ponytail: whole tar buffered in memory, 1 GiB ceiling; switch to spawn + pipe if the corpus ever approaches it.
+    tar = execFileSync('tar', ['-C', p.data, '-cf', '-', ...targets], { maxBuffer: 1 << 30 });
+  } catch (e) {
+    if (e.code === 'ENOENT') { process.stderr.write('export: tar is required and was not found on PATH\n'); return 1; }
+    const firstLine = e.stderr ? e.stderr.toString().split('\n').find((l) => l.length > 0) : undefined;
+    process.stderr.write(`export: tar failed: ${firstLine ?? e.message}\n`);
+    return 1;
+  }
+  process.stdout.write(tar);
+  process.stderr.write(`export: ${n} entries\n`);
+  return 0;
+}

package/src/cli/index.mjs

@@ -0,0 +1,12 @@
+import { paths } from '../paths.mjs';
+import { loadVocab } from '../vocab.mjs';
+import { buildIndex } from '../index/build.mjs';
+
+export async function run() {
+  const p = paths();
+  const r = await buildIndex({ entriesDir: p.entries, indexPath: p.index, vocab: loadVocab(p.vocab), models: p.models });
+  for (const m of r.refused) process.stderr.write(`refused ${m}\n`);
+  process.stdout.write(`indexed ${r.entries} entries, refused: ${r.refused.length}, arms: ${r.arms.join(',')}\n`);
+  for (const s of r.skipped) process.stderr.write(`embeddings: skipped (${s.reason})\n`);
+  return 0;
+}

package/src/cli/refresh.mjs

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { paths } from '../paths.mjs';
+import { parseEntry } from '../entry.mjs';
+import { loadVocab } from '../vocab.mjs';
+import { buildIndex } from '../index/build.mjs';
+import { measure } from '../ingest/measure.mjs';
+import { refuseUnsafeUrl } from '../ingest/url-guard.mjs';
+
+// Re-measures an entry that was drafted from a live URL: rewrites measure.json and
+// the two screenshots, bumps captured.at, and reindexes. Every judgement field
+// (roles, feel, palette, type, motion, body…) is untouched — only measure.json and
+// captured.at change. `transport` is undefined for the CLI, 'http' for the hosted
+// MCP server; the SSRF guard only consults DNS in the latter case.
+export async function refreshEntry({ slug, transport }) {
+  const p = paths();
+  const dir = path.join(p.entries, slug);
+  let e;
+  try { e = parseEntry(dir); } catch { return { refused: `no entry with slug ${slug}` }; }
+  const url = e.fm.source?.url;
+  const method = e.fm.captured?.method;
+  if (!url) return { refused: `${slug}: refresh needs source.url` };
+  if (method === 'frames') return { refused: `${slug}: refresh needs captured.method measured or both, not frames` };
+  const refusal = await refuseUnsafeUrl(url, { transport });
+  if (refusal) return { refused: refusal };
+
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'wpdl-refresh-'));
+  let result;
+  try {
+    result = await measure(url, scratch, {});
+  } catch (err) {
+    fs.rmSync(scratch, { recursive: true, force: true });
+    return { refused: `measure failed: ${err.message}` };
+  }
+  if (!result.ok) {
+    fs.rmSync(scratch, { recursive: true, force: true });
+    return { refused: result.error };
+  }
+  for (const f of ['measure.json', 'screen-1440.png', 'screen-390.png']) {
+    fs.copyFileSync(path.join(scratch, f), path.join(dir, f));
+  }
+  fs.rmSync(scratch, { recursive: true, force: true });
+
+  e.fm.captured.at = new Date().toISOString().slice(0, 10);
+  const body = e.body ? `\n${e.body}\n` : '';
+  fs.writeFileSync(path.join(dir, 'entry.md'), `---\n${yaml.dump(e.fm, { lineWidth: 120 })}---\n${body}`);
+
+  await buildIndex({ entriesDir: p.entries, indexPath: p.index, vocab: loadVocab(p.vocab), models: p.models });
+  return { ok: true, slug, captured: e.fm.captured };
+}
+
+export async function run(args) {
+  const slug = args[0];
+  if (!slug) {
+    process.stdout.write(JSON.stringify({ refused: 'refresh: slug is required' }) + '\n');
+    return 1;
+  }
+  const out = await refreshEntry({ slug });
+  process.stdout.write(JSON.stringify(out) + '\n');
+  return out.refused ? 1 : 0;
+}

package/src/cli/save.mjs

@@ -0,0 +1,16 @@
+import path from 'node:path';
+import { paths } from '../paths.mjs';
+import { loadVocab } from '../vocab.mjs';
+import { saveEntry } from '../ingest/save.mjs';
+
+export async function run(args) {
+  const p = paths();
+  const r = await saveEntry({ dir: path.join(p.entries, args[0]), vocab: loadVocab(p.vocab), indexPath: p.index, entriesDir: p.entries, models: p.models });
+  if (!r.ok) {
+    for (const m of r.errors) process.stderr.write(`${r.slug}: ${m}\n`);
+    process.stdout.write(JSON.stringify(r) + '\n');
+    return 1;
+  }
+  process.stdout.write(JSON.stringify(r) + '\n');
+  return 0;
+}

package/src/cli/serve.mjs

@@ -0,0 +1,64 @@
+async function syncSeed(p) {
+  const fs = await import('node:fs');
+  // Every start: copy seed entries the volume does not have yet. Never overwrite —
+  // the volume may hold hosted ingests and edits the image knows nothing about.
+  if (p.seed !== p.entries && fs.existsSync(p.seed)) {
+    const path = await import('node:path');
+    fs.mkdirSync(p.entries, { recursive: true });
+    let copied = 0;
+    for (const d of fs.readdirSync(p.seed, { withFileTypes: true })) {
+      if (!d.isDirectory() || !fs.existsSync(path.join(p.seed, d.name, 'entry.md'))) continue;
+      const dest = path.join(p.entries, d.name);
+      if (fs.existsSync(dest)) continue;
+      fs.cpSync(path.join(p.seed, d.name), dest, { recursive: true });
+      copied++;
+    }
+    process.stderr.write(`seed: copied ${copied} new entries into ${p.entries}\n`);
+  }
+}
+
+async function buildTheIndex(p) {
+  const { loadVocab } = await import('../vocab.mjs');
+  const { buildIndex } = await import('../index/build.mjs');
+  const r = await buildIndex({ entriesDir: p.entries, indexPath: p.index, vocab: loadVocab(p.vocab), models: p.models });
+  process.stderr.write(`index: ${r.entries} entries, refused ${r.refused.length}\n`);
+  for (const s of r.skipped) process.stderr.write(`embeddings: skipped (${s.reason})\n`);
+}
+
+async function fetchModelsOnStart(p) {
+  // The API must not depend on this: a failure (offline container, first deploy
+  // before the operator flips the flag back) is logged and swallowed, never thrown.
+  process.stderr.write('models: fetch start\n');
+  try {
+    const { fetchModels } = await import('../index/embed.mjs');
+    await fetchModels(p.models);
+    process.stderr.write('models: fetch finished\n');
+  } catch (err) {
+    process.stderr.write(`models: fetch failed, continuing: ${err.stack || err}\n`);
+  }
+}
+
+export async function run(args) {
+  const { paths } = await import('../paths.mjs');
+  const p = paths();
+  if (args.includes('--http')) {
+    const path = await import('node:path');
+    await syncSeed(p);
+    if (process.env.LIBRARY_FETCH_MODELS === '1') await fetchModelsOnStart(p);
+    await buildTheIndex(p);
+    try {
+      const { buildUi } = await import('../ui/build.mjs');
+      await buildUi({ indexPath: p.index, entriesDir: p.entries, outDir: path.join(p.data, 'ui') });
+    } catch (err) {
+      // the gallery is a convenience for a human; the MCP API must not depend on it
+      process.stderr.write(`ui: build failed, serving without it: ${err.stack || err}\n`);
+    }
+    const { serveHttp } = await import('../mcp/http.mjs');
+    return serveHttp();
+  }
+  await syncSeed(p);
+  await buildTheIndex(p);
+  const { serveStdio } = await import('../mcp/server.mjs');
+  await serveStdio();
+  return new Promise(() => {}); // stay alive until the client closes stdin
+}

package/src/cli/ui.mjs

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

package/src/entry.mjs

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { resolveTerm } from './vocab.mjs';
+
+export const REQUIRED_BLANKS = ['roles', 'feel', 'motion.devices', 'motion.notes', 'type.display', 'type.body', 'body',
+  'palette.canvas', 'palette.ink', 'palette.accent'];
+const REQUIRED = ['slug', 'title', 'tier', 'source.kind', 'source.license', 'captured.method', 'captured.at', 'captured.tool',
+  ...REQUIRED_BLANKS];
+
+export function parseEntry(dir) {
+  const file = path.join(dir, 'entry.md');
+  const text = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
+  const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(text);
+  if (!m) throw new Error(`${file}: no frontmatter`);
+  const fm = yaml.load(m[1]) ?? {};
+  return { slug: fm.slug, dir, fm, body: m[2].trim() };
+}
+
+function get(obj, dotted) {
+  return dotted.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
+}
+function blank(v) {
+  return v == null || v === '' || (Array.isArray(v) && v.length === 0);
+}
+
+export function validateEntry(entry, vocab) {
+  const errors = [];
+  const { fm } = entry;
+  if (fm.slug !== path.basename(entry.dir)) errors.push('slug: must equal the directory name');
+  const view = { ...fm, body: entry.body };
+  for (const k of REQUIRED) if (blank(get(view, k))) errors.push(`${k}: required, blank`);
+
+  const facetOf = { roles: 'role', feel: 'feel' };
+  for (const [key, facet] of Object.entries(facetOf)) {
+    if (!Array.isArray(fm[key])) continue;
+    fm[key] = fm[key].map((t) => {
+      const c = resolveTerm(vocab, facet, t);
+      if (c === null) errors.push(`${key}: unknown ${facet} term "${t}"`);
+      return c ?? t;
+    });
+  }
+  if (Array.isArray(fm.motion?.devices)) {
+    fm.motion.devices = fm.motion.devices.map((t) => {
+      const c = resolveTerm(vocab, 'motion', t);
+      if (c === null) errors.push(`motion.devices: unknown motion term "${t}"`);
+      return c ?? t;
+    });
+  }
+  if (fm.source?.kind && resolveTerm(vocab, 'source', fm.source.kind) === null)
+    errors.push(`source.kind: unknown source term "${fm.source.kind}"`);
+  if (fm.tier && resolveTerm(vocab, 'tier', fm.tier) === null)
+    errors.push(`tier: unknown tier term "${fm.tier}"`);
+
+  if (fm.tier === 'ported') {
+    if (['paid', 'public-site'].includes(fm.source?.kind))
+      errors.push(`licence gate: tier ported is not allowed with source.kind ${fm.source.kind}`);
+    if (blank(fm.ported_from)) errors.push('ported_from: required for tier ported');
+  }
+  if (!fs.existsSync(path.join(entry.dir, 'strip.png'))) errors.push('strip.png: missing');
+  return { ok: errors.length === 0, errors };
+}
+
+export function listEntries(entriesDir) {
+  if (!fs.existsSync(entriesDir)) return [];
+  return fs.readdirSync(entriesDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && fs.existsSync(path.join(entriesDir, d.name, 'entry.md')))
+    .map((d) => path.join(entriesDir, d.name));
+}

package/src/index/build.mjs

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { listEntries, parseEntry, validateEntry } from '../entry.mjs';
+import { openIndex } from './query.mjs';
+import { getEmbedder, absentReason } from './embed.mjs';
+
+const DIR = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA = fs.readFileSync(path.join(DIR, 'schema.sql'), 'utf8');
+const SCHEMA_VEC = fs.readFileSync(path.join(DIR, 'schema-vec.sql'), 'utf8');
+
+function isoDate(v) {
+  return v instanceof Date ? v.toISOString().slice(0, 10) : String(v).slice(0, 10);
+}
+
+export async function buildIndex({ entriesDir, indexPath, vocab, models }) {
+  fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+  const tmpPath = indexPath + '.tmp';
+  // a killed build can leave a half-written .tmp behind; clear it so the open below always starts fresh
+  fs.rmSync(tmpPath, { force: true });
+  let db;
+  try {
+    db = openIndex(tmpPath, { readonly: false });
+    db.exec(SCHEMA);
+    if (db.vec) db.exec(SCHEMA_VEC);
+    const emb = await getEmbedder({ models });
+    const refused = [];
+    const insEntry = db.prepare(`INSERT INTO entries VALUES (@slug,@title,@tier,@source_kind,@captured_at,@dir,@body,@fm)`);
+    const insTag = db.prepare(`INSERT INTO entry_tags VALUES (?,?,?)`);
+    const insFts = db.prepare(`INSERT INTO entries_fts(slug,title,body,tags) VALUES (?,?,?,?)`);
+    const insVecText = db.vec ? db.prepare(`INSERT INTO vec_text(slug, embedding) VALUES (?,?)`) : null;
+    const insVecImage = db.vec ? db.prepare(`INSERT INTO vec_image(slug, embedding) VALUES (?,?)`) : null;
+    const tx = db.transaction((e, tags) => {
+      insEntry.run({ slug: e.slug, title: e.fm.title, tier: e.fm.tier, source_kind: e.fm.source.kind,
+        captured_at: isoDate(e.fm.captured.at), dir: e.dir, body: e.body, fm: JSON.stringify(e.fm) });
+      for (const [f, t] of tags) insTag.run(e.slug, f, t);
+      insFts.run(e.slug, e.fm.title, e.body, tags.map(([f, t]) => `${f}/${t}`).join(' '));
+    });
+    let n = 0;
+    for (const dir of listEntries(entriesDir)) {
+      let e;
+      try { e = parseEntry(dir); } catch (err) { refused.push(`${path.basename(dir)}: ${err.message}`); continue; }
+      const r = validateEntry(e, vocab);
+      if (!r.ok) { refused.push(`${e.slug}: ${r.errors.join('; ')}`); continue; }
+      const tags = [
+        ...e.fm.roles.map((t) => ['role', t]),
+        ...e.fm.feel.map((t) => ['feel', t]),
+        ...e.fm.motion.devices.map((t) => ['motion', t]),
+        ['source', e.fm.source.kind], ['tier', e.fm.tier],
+      ];
+      tx(e, tags);
+      if (emb && db.vec) {
+        const tagsStr = tags.map(([f, t]) => `${f}/${t}`).join(' ');
+        const tv = await emb.text(e.fm.title + '\n' + e.body + '\n' + tagsStr);
+        insVecText.run(e.slug, Buffer.from(tv.buffer));
+        const iv = await emb.image(path.join(e.dir, 'strip.png'));
+        insVecImage.run(e.slug, Buffer.from(iv.buffer));
+      }
+      n++;
+    }
+    db.close();
+    fs.renameSync(tmpPath, indexPath);
+    return {
+      entries: n, refused,
+      arms: emb && db.vec ? ['fts', 'vec'] : ['fts'],
+      skipped: emb
+        ? (db.vec ? [] : [{ arm: 'vec', reason: 'sqlite-vec failed to load' }])
+        : [{ arm: 'vec', reason: absentReason(models) ?? 'LIBRARY_EMBED=off' }],
+    };
+  } catch (err) {
+    // buildIndex runs on every save_entry in the long-lived http server; an unclosed
+    // handle here leaks for the life of the process. A close failure must not mask
+    // the original error, so it's swallowed rather than rethrown.
+    try { db?.close(); } catch {}
+    fs.rmSync(tmpPath, { force: true });
+    throw err;
+  }
+}

package/src/index/embed.mjs

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+const TEXT_MODEL = 'Xenova/all-MiniLM-L6-v2';     // 384-d
+const IMAGE_MODEL = 'Xenova/siglip-base-patch16-224'; // 768-d
+export const DIMS = { text: 384, image: 768 };
+
+function stubVec(seed, n) {
+  // ponytail: hash-derived unit vector; deterministic, offline, no semantics. Real arm needs models.
+  const out = new Float32Array(n);
+  let h = createHash('sha256').update(seed).digest();
+  for (let i = 0; i < n; i++) { if (i % 32 === 0 && i) h = createHash('sha256').update(h).digest(); out[i] = (h[i % 32] / 255) * 2 - 1; }
+  const norm = Math.hypot(...out) || 1;
+  return out.map((v) => v / norm);
+}
+
+export function modelDirs(models) {
+  return { text: path.join(models, TEXT_MODEL), image: path.join(models, IMAGE_MODEL) };
+}
+
+export async function getEmbedder({ models, mode = process.env.LIBRARY_EMBED } = {}) {
+  if (mode === 'off') return null;
+  if (mode === 'stub') {
+    return {
+      arm: 'vec', dims: DIMS,
+      text: async (s) => stubVec('t:' + s, DIMS.text),
+      // ponytail: seeded on byte length + basename, not pixel content. Every
+      // indexed strip shares the basename strip.png, so two strips of the same
+      // byte length collide on the same vector — fine for exercising the vec
+      // arm offline, not a stand-in for real image similarity.
+      image: async (p) => stubVec('i:' + fs.readFileSync(p).length + ':' + path.basename(p), DIMS.image),
+    };
+  }
+  const d = modelDirs(models);
+  if (!fs.existsSync(d.text) || !fs.existsSync(d.image)) return null; // caller reads absentReason()
+  const tf = await import('@huggingface/transformers');
+  tf.env.cacheDir = models; tf.env.allowRemoteModels = process.env.LIBRARY_FETCH_MODELS === '1';
+  const textPipe = await tf.pipeline('feature-extraction', TEXT_MODEL);
+  const proc = await tf.AutoProcessor.from_pretrained(IMAGE_MODEL);
+  const vision = await tf.SiglipVisionModel.from_pretrained(IMAGE_MODEL);
+  return {
+    arm: 'vec', dims: DIMS,
+    text: async (s) => Float32Array.from((await textPipe(s, { pooling: 'mean', normalize: true })).data),
+    image: async (p) => {
+      const img = await tf.RawImage.read(p);
+      const out = await vision(await proc(img));
+      const v = Float32Array.from(out.pooler_output.data); const n = Math.hypot(...v) || 1;
+      return v.map((x) => x / n);
+    },
+  };
+}
+
+export function absentReason(models, mode = process.env.LIBRARY_EMBED) {
+  // An explicit opt-out is the reason on its own; do not let a stale/present
+  // model dir on disk relabel it, and do not touch the filesystem to find out.
+  if (mode === 'off') return 'LIBRARY_EMBED=off';
+  const d = modelDirs(models);
+  const missing = Object.entries(d).filter(([, p]) => !fs.existsSync(p)).map(([k]) => k);
+  return missing.length ? `models absent: ${missing.join(', ')} under ${models}` : null;
+}
+
+export async function fetchModels(models) {
+  const tf = await import('@huggingface/transformers');
+  tf.env.cacheDir = models; tf.env.allowRemoteModels = true;
+  await tf.pipeline('feature-extraction', TEXT_MODEL);
+  await tf.AutoProcessor.from_pretrained(IMAGE_MODEL);
+  await tf.SiglipVisionModel.from_pretrained(IMAGE_MODEL);
+}