@birdapi/velinstyle 1.2.2 → 1.3.0

package/core/motion/timeline.js

@@ -0,0 +1,68 @@
+/**
+ * Timeline Engine — Scene → Timeline → Steps (Registry-backed).
+ */
+import { getTimeline } from './registry.js';
+import { markVisible, prefersReducedMotion } from './effects.js';
+
+/**
+ * Run a registered timeline against a root element.
+ * Steps resolve `[data-velin-step="id"]` or `#id` or `[velin-step="id"]`.
+ * @param {string} timelineId
+ * @param {ParentNode} root
+ * @param {{ stepMs?: number, policyDisabled?: boolean }} [opts]
+ * @returns {{ ok: boolean, error?: string, ran: string[] }}
+ */
+export function runTimeline(timelineId, root, opts = {}) {
+  const tl = getTimeline(timelineId);
+  if (!tl) return { ok: false, error: `Unknown timeline "${timelineId}"`, ran: [] };
+  const stepMs = opts.stepMs ?? 120;
+  const ran = [];
+
+  if (opts.policyDisabled || prefersReducedMotion()) {
+    for (const step of tl.steps || []) {
+      const el = resolveStep(root, step);
+      if (el) markVisible(el);
+      ran.push(step);
+    }
+    return { ok: true, ran };
+  }
+
+  let delay = 0;
+  for (const step of tl.steps || []) {
+    const el = resolveStep(root, step);
+    if (!el) continue;
+    const d = delay;
+    delay += stepMs;
+    if (typeof window !== 'undefined' && window.setTimeout) {
+      window.setTimeout(() => markVisible(el), d);
+    } else {
+      markVisible(el);
+    }
+    ran.push(step);
+  }
+  return { ok: true, ran, timeline: tl };
+}
+
+function resolveStep(root, step) {
+  if (!root?.querySelector) return null;
+  return (
+    root.querySelector(`[data-velin-step="${step}"]`)
+    || root.querySelector(`[velin-step="${step}"]`)
+    || root.querySelector(`#${CSS.escape?.(step) || step}`)
+  );
+}
+
+/**
+ * Enhance `[velin-timeline="id"]` roots.
+ */
+export function enhanceTimelines(root) {
+  if (!root?.querySelectorAll) return () => {};
+  const nodes = root.querySelectorAll('[velin-timeline]');
+  const teardowns = [];
+  for (const el of nodes) {
+    const id = el.getAttribute('velin-timeline');
+    const result = runTimeline(id, el);
+    teardowns.push(() => result);
+  }
+  return () => {};
+}

package/core/motion/transitions.js

@@ -0,0 +1,49 @@
+/**
+ * Transition helpers (View Transition + overlay hooks).
+ */
+import { getMotion } from './registry.js';
+
+/**
+ * Run a document view transition if supported.
+ * @param {() => void|Promise<void>} updateCallback
+ * @param {{ name?: string }} [opts]
+ */
+export async function runViewTransition(updateCallback, opts = {}) {
+  const doc = typeof document !== 'undefined' ? document : null;
+  if (!doc) {
+    await updateCallback();
+    return { ok: true, mode: 'direct' };
+  }
+  if (typeof doc.startViewTransition === 'function') {
+    const vt = doc.startViewTransition(async () => {
+      if (opts.name && doc.documentElement) {
+        doc.documentElement.style.viewTransitionName = opts.name;
+      }
+      await updateCallback();
+    });
+    await vt.finished.catch(() => {});
+    return { ok: true, mode: 'view-transition', id: opts.name || null };
+  }
+  await updateCallback();
+  return { ok: true, mode: 'fallback' };
+}
+
+export function getTransitionPreset(id) {
+  return getMotion('transitions', id);
+}
+
+/**
+ * Apply transition class hints for modal/drawer hosts.
+ * @param {HTMLElement} el
+ * @param {'modal-enter'|'drawer-enter'|'cross-fade'} id
+ */
+export function applyTransitionHint(el, id) {
+  if (!el) return;
+  const map = {
+    'modal-enter': 'velin-animate-fade-in',
+    'drawer-enter': 'velin-animate-on-scroll--slide-right',
+    'cross-fade': 'velin-animate-fade-in',
+  };
+  const cls = map[id];
+  if (cls) el.classList.add(cls);
+}

package/core/motion/triggers.js

@@ -0,0 +1,168 @@
+/**
+ * Motion Trigger Engine — when motion starts (First-Class, Studio-ready).
+ */
+import { observeInView } from './scheduler.js';
+import { markVisible, prefersReducedMotion } from './effects.js';
+import { getTrigger } from './registry.js';
+
+export const TRIGGER_V1 = ['load', 'visible', 'hover', 'focus', 'click', 'scroll'];
+export const TRIGGER_V2 = ['hidden', 'idle', 'media', 'container', 'theme', 'custom'];
+export const ALL_TRIGGERS = [...TRIGGER_V1, ...TRIGGER_V2];
+
+/**
+ * Read trigger id from element (velin-trigger or default).
+ * @param {HTMLElement} el
+ * @param {string} [fallback='visible']
+ */
+export function readTrigger(el, fallback = 'visible') {
+  const raw = (el.getAttribute('velin-trigger') || fallback || 'visible').trim().toLowerCase();
+  return raw || fallback;
+}
+
+/**
+ * Bind a trigger to run `onFire` once (or per event).
+ * @param {HTMLElement} el
+ * @param {string} triggerId
+ * @param {() => void} onFire
+ * @param {{ once?: boolean, reduced?: boolean }} [opts]
+ * @returns {() => void} teardown
+ */
+export function bindTrigger(el, triggerId, onFire, opts = {}) {
+  const once = opts.once !== false;
+  const reduced = opts.reduced ?? prefersReducedMotion();
+  const id = (triggerId || 'visible').toLowerCase();
+  const meta = getTrigger(id);
+
+  if (reduced || el.dataset.velinMotion === 'off') {
+    onFire();
+    return () => {};
+  }
+
+  if (meta?.status === 'planned' && !TRIGGER_V1.includes(id)) {
+    // Planned V2 triggers are not first-class yet: fall back to visible for runtime safety
+    return bindTrigger(el, 'visible', onFire, opts);
+  }
+
+  let fired = false;
+  const fire = () => {
+    if (once && fired) return;
+    fired = true;
+    onFire();
+  };
+
+  if (id === 'load') {
+    fire();
+    return () => {};
+  }
+
+  if (id === 'visible' || id === 'scroll') {
+    return observeInView(el, () => fire());
+  }
+
+  if (id === 'hover') {
+    const enter = () => fire();
+    el.addEventListener('pointerenter', enter);
+    return () => el.removeEventListener('pointerenter', enter);
+  }
+
+  if (id === 'focus') {
+    const onFocus = () => fire();
+    el.addEventListener('focusin', onFocus);
+    return () => el.removeEventListener('focusin', onFocus);
+  }
+
+  if (id === 'click') {
+    const onClick = () => fire();
+    el.addEventListener('click', onClick);
+    return () => el.removeEventListener('click', onClick);
+  }
+
+  if (id === 'hidden') {
+    const stop = observeInView(el, () => {
+      /* enter */
+    });
+    // Fallback: use IntersectionObserver with leave
+    if (typeof IntersectionObserver === 'undefined') return () => {};
+    const io = new IntersectionObserver((entries) => {
+      for (const entry of entries) {
+        if (!entry.isIntersecting) fire();
+      }
+    }, { threshold: 0 });
+    io.observe(el);
+    return () => {
+      stop();
+      io.disconnect();
+    };
+  }
+
+  if (id === 'idle') {
+    const ms = Number(el.getAttribute('velin-trigger-delay') || 3000);
+    const t = setTimeout(fire, ms);
+    return () => clearTimeout(t);
+  }
+
+  if (id === 'media') {
+    const q = el.getAttribute('velin-trigger-media') || '(min-width: 768px)';
+    if (typeof window === 'undefined' || !window.matchMedia) {
+      fire();
+      return () => {};
+    }
+    const mql = window.matchMedia(q);
+    const handler = () => {
+      if (mql.matches) fire();
+    };
+    handler();
+    mql.addEventListener?.('change', handler);
+    return () => mql.removeEventListener?.('change', handler);
+  }
+
+  if (id === 'theme') {
+    const root = el.ownerDocument?.documentElement;
+    if (!root || typeof MutationObserver === 'undefined') {
+      fire();
+      return () => {};
+    }
+    const mo = new MutationObserver(() => fire());
+    mo.observe(root, { attributes: true, attributeFilter: ['data-velin-theme', 'class'] });
+    return () => mo.disconnect();
+  }
+
+  if (id === 'custom') {
+    const evt = el.getAttribute('velin-trigger-event') || 'velin:motion';
+    const handler = () => fire();
+    el.addEventListener(evt, handler);
+    return () => el.removeEventListener(evt, handler);
+  }
+
+  if (id === 'container') {
+    // Approximate with visible until container queries runtime ships
+    return observeInView(el, () => fire());
+  }
+
+  // Unknown → visible
+  return observeInView(el, () => fire());
+}
+
+/**
+ * Apply motion classes then bind trigger to markVisible.
+ * @param {HTMLElement} el
+ * @param {() => void} applyPreset
+ */
+export function armMotionElement(el, applyPreset) {
+  applyPreset();
+  const trigger = readTrigger(el, el.hasAttribute('velin-hover') ? 'hover' : 'visible');
+  if (prefersReducedMotion() || el.dataset.velinMotion === 'off') {
+    markVisible(el);
+    return () => {};
+  }
+  if (trigger === 'hover' || trigger === 'focus') {
+    // CSS hover classes already apply; still mark visible for scroll classes
+    markVisible(el);
+    return () => {};
+  }
+  if (trigger === 'load') {
+    markVisible(el);
+    return () => {};
+  }
+  return bindTrigger(el, trigger, () => markVisible(el));
+}

package/core/security/checks/fs.js

@@ -0,0 +1,92 @@
+/**
+ * Shared FS helpers for Security Engine rules.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join, relative } from 'path';
+
+const SKIP = new Set(['node_modules', '.git', 'dist', 'vendor', 'coverage', '.velin']);
+
+/**
+ * @param {string} root
+ * @param {(name: string, abs: string) => boolean} [filter]
+ * @param {number} [max=400]
+ */
+export function walkFiles(root, filter, max = 400) {
+  const out = [];
+  const walk = (dir) => {
+    if (out.length >= max) return;
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (SKIP.has(name)) continue;
+      const abs = join(dir, name);
+      let st;
+      try {
+        st = statSync(abs);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) walk(abs);
+      else if (!filter || filter(name, abs)) out.push(abs);
+      if (out.length >= max) return;
+    }
+  };
+  if (existsSync(root)) walk(root);
+  return out;
+}
+
+export function readText(path) {
+  try {
+    return readFileSync(path, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+export function readJson(path) {
+  const t = readText(path);
+  if (!t) return null;
+  try {
+    return JSON.parse(t);
+  } catch {
+    return null;
+  }
+}
+
+export function rel(root, abs) {
+  return relative(root, abs).replace(/\\/g, '/');
+}
+
+export function fileExists(path) {
+  return existsSync(path);
+}
+
+/**
+ * Lightweight YAML-ish peek for GitHub Actions (no full parser).
+ * @param {string} text
+ */
+export function workflowHints(text) {
+  const lines = text.split(/\r?\n/);
+  const uses = [];
+  let hasPullRequestTarget = /pull_request_target\s*:/.test(text);
+  let hasPermissions = /^\s*permissions\s*:/m.test(text);
+  let hasIdToken = /id-token\s*:\s*write/.test(text);
+  let mentionsNpmToken = /NPM_TOKEN|NODE_AUTH_TOKEN/.test(text);
+  for (const line of lines) {
+    const m = line.match(/^\s*-\s*uses:\s*(.+)\s*$/);
+    if (m) uses.push(m[1].trim().replace(/['"]/g, ''));
+  }
+  return { uses, hasPullRequestTarget, hasPermissions, hasIdToken, mentionsNpmToken };
+}
+
+/** Pin check: owner/action@sha40 vs @v1 */
+export function isShaPinned(usesRef) {
+  const at = usesRef.lastIndexOf('@');
+  if (at < 0) return false;
+  const ref = usesRef.slice(at + 1);
+  return /^[0-9a-f]{40}$/i.test(ref);
+}

package/core/security/detect.js

@@ -0,0 +1,35 @@
+/**
+ * Detect repo vs consumer vs both for Security Engine.
+ */
+import { join } from 'path';
+import { fileExists, readJson } from './checks/fs.js';
+
+/**
+ * @param {string} root
+ * @returns {'repo'|'consumer'|'both'}
+ */
+export function detectSecurityMode(root) {
+  const pkg = readJson(join(root, 'package.json'));
+  const isFramework =
+    pkg?.name === '@birdapi/velinstyle'
+    || fileExists(join(root, '.github', 'workflows', 'publish-npm.yml'))
+    || (fileExists(join(root, 'SECURITY.md')) && fileExists(join(root, 'cli', 'index.js')));
+
+  const hasVelinDep =
+    Boolean(pkg?.dependencies?.['@birdapi/velinstyle'] || pkg?.devDependencies?.['@birdapi/velinstyle'])
+    || fileExists(join(root, 'vendor', 'velinstyle'))
+    || fileExists(join(root, 'vendor', 'velinstyle.min.css'));
+
+  const consumerMarkers =
+    fileExists(join(root, 'artisan'))
+    || fileExists(join(root, 'composer.json'))
+    || hasVelinDep
+    || Boolean(pkg && pkg.name !== '@birdapi/velinstyle');
+
+  if (isFramework && consumerMarkers && hasVelinDep && pkg?.name !== '@birdapi/velinstyle') {
+    return 'both';
+  }
+  if (isFramework) return 'repo';
+  if (consumerMarkers || pkg) return 'consumer';
+  return 'consumer';
+}

package/core/security/engine.js

@@ -0,0 +1,116 @@
+/**
+ * Velin Security Engine — run registered rules.
+ */
+import { selectSecurityRules } from './registry.js';
+import { loadBuiltinSecurityRules } from './rules/index.js';
+import { detectSecurityMode } from './detect.js';
+import { scoreFindings } from './score/score.js';
+import { computeDependencyHealth } from './score/dependency-health.js';
+import { computeReleaseHealth } from './score/release-health.js';
+import { loadTimeline, touchTimeline } from './timeline/timeline.js';
+import { resolve } from 'path';
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.root]
+ * @param {string} [opts.mode] — doctor|repo|consumer|ci|publish|deps|secrets|scan|audit
+ * @param {string[]} [opts.categories]
+ * @param {boolean} [opts.updateTimeline=true]
+ * @param {boolean} [opts.includeReleaseHealth]
+ * @param {boolean} [opts.includeDependencyHealth]
+ */
+export async function runSecurityEngine(opts = {}) {
+  loadBuiltinSecurityRules();
+  const root = resolve(opts.root || '.');
+  let mode = opts.mode || 'doctor';
+
+  let detected = detectSecurityMode(root);
+  if (mode === 'doctor') {
+    mode = detected === 'both' ? 'audit' : detected;
+  }
+
+  const categoryMap = {
+    deps: ['deps', 'malware'],
+    secrets: ['secrets'],
+    ci: ['ci'],
+    publish: ['publish', 'repo', 'secrets', 'deps', 'malware'],
+    scan: ['consumer', 'secrets', 'repo', 'malware'],
+    repo: ['repo', 'ci', 'secrets', 'deps', 'publish', 'malware'],
+    consumer: ['consumer', 'secrets', 'deps', 'malware'],
+    audit: null,
+  };
+
+  const categories = opts.categories || categoryMap[mode] || null;
+  const rules = selectSecurityRules({
+    mode: mode === 'audit' ? 'audit' : mode,
+    categories: categories || undefined,
+  });
+
+  const ctx = { root, mode, categories: categories || undefined, meta: { detected } };
+  /** @type {import('./registry.js').SecurityFinding[]} */
+  const findings = [];
+
+  for (const rule of rules) {
+    try {
+      const out = await rule.run(ctx);
+      for (const f of out || []) {
+        findings.push({
+          category: rule.category,
+          ...f,
+          ruleId: f.ruleId || rule.id,
+        });
+      }
+    } catch (err) {
+      findings.push({
+        ruleId: rule.id,
+        category: rule.category,
+        severity: 'warning',
+        message: `Rule failed: ${err?.message || err}`,
+      });
+    }
+  }
+
+  const scored = scoreFindings(findings);
+  const includeDep = opts.includeDependencyHealth !== false;
+  const includeRel =
+    opts.includeReleaseHealth === true
+    || mode === 'publish'
+    || (mode === 'audit' && detected === 'repo');
+
+  const dependencyHealth = includeDep ? computeDependencyHealth(root, findings) : null;
+  const releaseHealth = includeRel ? computeReleaseHealth(root, findings) : null;
+
+  const touched = [];
+  if (mode === 'ci' || categories?.includes('ci')) touched.push('ci');
+  if (mode === 'deps' || categories?.includes('deps')) touched.push('dependencies');
+  if (mode === 'secrets' || categories?.includes('secrets')) touched.push('secrets');
+  if (mode === 'publish') touched.push('publish');
+  if (mode === 'repo' || detected === 'repo') touched.push('repository');
+  if (mode === 'consumer' || detected === 'consumer') touched.push('consumer');
+  if (mode === 'audit' || mode === 'scan') touched.push('audit');
+
+  let timeline = loadTimeline(root);
+  if (opts.updateTimeline !== false && touched.length) {
+    timeline = touchTimeline(root, touched);
+  }
+
+  return {
+    ...scored,
+    root,
+    mode,
+    detected,
+    rulesRun: rules.length,
+    dependencyHealth,
+    releaseHealth,
+    timeline,
+    ok: scored.overallGate !== 'fail',
+  };
+}
+
+export function createSecurityEngine(options = {}) {
+  loadBuiltinSecurityRules();
+  return {
+    detect: (root) => detectSecurityMode(resolve(root || options.root || '.')),
+    run: (opts = {}) => runSecurityEngine({ ...options, ...opts }),
+  };
+}

package/core/security/index.js

@@ -0,0 +1,18 @@
+/**
+ * Velin Security Engine — public API.
+ */
+export {
+  registerSecurityRule,
+  clearSecurityRules,
+  listSecurityRules,
+  getSecurityRule,
+  selectSecurityRules,
+} from './registry.js';
+export { detectSecurityMode } from './detect.js';
+export { runSecurityEngine, createSecurityEngine } from './engine.js';
+export { scoreFindings, gateLabel } from './score/score.js';
+export { computeDependencyHealth } from './score/dependency-health.js';
+export { computeReleaseHealth } from './score/release-health.js';
+export { loadTimeline, touchTimeline, timelineRows, timelinePath } from './timeline/timeline.js';
+export { toExperiencePayload, toMarkdownReport } from './report/report.js';
+export { loadBuiltinSecurityRules } from './rules/index.js';

package/core/security/registry.js

@@ -0,0 +1,85 @@
+/**
+ * Velin Security Engine — rule registry (Studio-/CLI-ready).
+ */
+
+/** @typedef {'ci'|'secrets'|'deps'|'publish'|'repo'|'consumer'|'malware'} SecurityCategory */
+/** @typedef {'info'|'warning'|'error'} SecuritySeverity */
+/** @typedef {'repo'|'consumer'|'ci'|'publish'|'deps'|'secrets'|'scan'|'audit'} SecurityMode */
+
+/**
+ * @typedef {object} SecurityFinding
+ * @property {string} ruleId
+ * @property {SecuritySeverity} severity
+ * @property {string} message
+ * @property {string} [path]
+ * @property {string} [fix]
+ * @property {string} [code]
+ */
+
+/**
+ * @typedef {object} SecurityRule
+ * @property {string} id
+ * @property {SecurityCategory} category
+ * @property {SecuritySeverity} severity
+ * @property {SecurityMode[]} [modes]
+ * @property {string} [title]
+ * @property {string} [description]
+ * @property {(ctx: SecurityContext) => Promise<SecurityFinding[]>|SecurityFinding[]} run
+ */
+
+/**
+ * @typedef {object} SecurityContext
+ * @property {string} root
+ * @property {SecurityMode} mode
+ * @property {string[]} [categories]
+ * @property {import('fs').PathLike} [fs]
+ * @property {Record<string, unknown>} [meta]
+ */
+
+/** @type {Map<string, SecurityRule>} */
+const RULES = new Map();
+
+/**
+ * @param {SecurityRule} rule
+ */
+export function registerSecurityRule(rule) {
+  if (!rule?.id || typeof rule.run !== 'function') {
+    throw new Error('registerSecurityRule: id and run() required');
+  }
+  RULES.set(rule.id, {
+    severity: 'warning',
+    modes: ['repo', 'consumer', 'audit'],
+    title: rule.id,
+    description: '',
+    ...rule,
+  });
+  return rule.id;
+}
+
+export function clearSecurityRules() {
+  RULES.clear();
+}
+
+export function listSecurityRules() {
+  return [...RULES.values()];
+}
+
+export function getSecurityRule(id) {
+  return RULES.get(id) || null;
+}
+
+/**
+ * @param {{ mode?: SecurityMode, categories?: string[] }} [filter]
+ */
+export function selectSecurityRules(filter = {}) {
+  const mode = filter.mode;
+  const cats = filter.categories?.length ? new Set(filter.categories) : null;
+  return listSecurityRules().filter((r) => {
+    if (cats && !cats.has(r.category)) return false;
+    if (!mode) return true;
+    const modes = r.modes || [];
+    if (mode === 'audit' || mode === 'doctor') return true;
+    if (mode === 'scan') return modes.includes('scan') || modes.includes('consumer') || modes.includes('secrets');
+    return modes.includes(mode) || modes.includes('audit');
+  });
+}