@birdapi/velinstyle 1.2.2 → 1.3.0

package/packages/velinstyle-motion/src/index.js

@@ -0,0 +1,304 @@
+/**
+ * @birdapi/velinstyle-motion — public API
+ */
+export { assertMotionImageFile, MOTION_IMAGE_EXTENSIONS } from './validate-image.js';
+export {
+  loadMotionConfig,
+  ensureMotionDirs,
+  motionDir,
+  MOTION_CONFIG_DEFAULTS,
+  hasPixVerseApiKey,
+  savePixVerseApiKey,
+  markPixVerseSetupCompleted,
+  isPixVerseSetupCompleted,
+  redactSecrets,
+  safeErrorMessage,
+  loadMotionDotEnv,
+} from './config.js';
+export { listClipPresets, getClipPreset, listWizardChoices } from './registry/presets.js';
+export { createLocalClip, createLocalTransition, createEffectClip } from './local/engine.js';
+export { listLocalEffectIds, profileToLocalEffects } from './local/effects.js';
+export { exportHtmlClip } from './export/html-clip.js';
+export {
+  registerAiProvider,
+  getAiProvider,
+  listAiProviders,
+  loadBuiltinAiProviders,
+  providerHas,
+} from './ai/provider.js';
+export { createPixVerseProvider } from './ai/providers/pixverse.js';
+export {
+  runPixVerseSetup,
+  openPixVerseSignup,
+  pixVerseSignupUrl,
+  formatPixVerseSignupHelp,
+  formatPixVerseOpenAccountHelp,
+  formatPixVerseOpenFailedHelp,
+  formatPixVerseTrackerHint,
+  copyPixVersePartnerLink,
+  runPixVersePartnerOpenFlow,
+  PIXVERSE_AFFILIATE_URL,
+  PIXVERSE_DIRECT_URL,
+  PIXVERSE_DOCS_URL,
+  PIXVERSE_KEY_MISSING_HINT,
+  testPixVerseConnection,
+} from './ai/providers/pixverse-setup.js';
+export { suggestFromMiniPrompt, profileToAiPrompt } from './ai/mini-prompt.js';
+export { runCreateWizard, runAtelierWizard } from './ux/wizard.js';
+export { confirmAiCost } from './ux/cost-gate.js';
+export { ensurePixVerseReady } from './ux/pixverse-gate.js';
+export { createJob, finishJob, listJobs, loadJob } from './jobs/queue.js';
+export { getUsageSummary } from './jobs/usage.js';
+export { listMotionProviders, formatMotionProvidersText } from './providers-catalog.js';
+
+import { loadMotionConfig, hasPixVerseApiKey, safeErrorMessage } from './config.js';
+import { getClipPreset } from './registry/presets.js';
+import { createLocalClip, createLocalTransition } from './local/engine.js';
+import { loadBuiltinAiProviders, getAiProvider } from './ai/provider.js';
+import { confirmAiCost } from './ux/cost-gate.js';
+import { ensurePixVerseReady } from './ux/pixverse-gate.js';
+import { createJob, finishJob } from './jobs/queue.js';
+import { profileToAiPrompt } from './ai/mini-prompt.js';
+import { assertMotionImageFile } from './validate-image.js';
+import { readdirSync, existsSync, statSync } from 'fs';
+import { join, resolve, extname } from 'path';
+
+/**
+ * Resolve dry-run: only explicit flag / env — never auto on missing key.
+ * @param {object} opts
+ */
+function resolveDryRun(opts) {
+  return Boolean(opts.dryRun || process.env.VELIN_MOTION_DRY_RUN === '1');
+}
+
+/**
+ * High-level create: local or AI based on options.
+ * @param {object} opts
+ */
+export async function createMotionClip(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const cfg = loadMotionConfig(cwd);
+  const preset = getClipPreset(opts.preset || 'soft-zoom');
+  const engine = opts.engine || (preset?.engine === 'ai' ? 'ai' : 'local');
+
+  if (engine !== 'ai') {
+    return createLocalClip({
+      cwd,
+      image: opts.image,
+      preset: preset?.id || opts.preset || 'soft-zoom',
+      duration: opts.duration ?? cfg.default_duration,
+      outDir: opts.outDir || cfg.output_dir,
+      profile: opts.profile,
+      effects: opts.effects,
+    });
+  }
+
+  const imageAbs = resolve(cwd, opts.image);
+  assertMotionImageFile(imageAbs, 'Image');
+
+  const dryRun = resolveDryRun(opts);
+  await ensurePixVerseReady({
+    cwd,
+    yes: opts.yes,
+    quiet: opts.quiet,
+    json: opts.json,
+    dryRun,
+    openImpl: opts.openImpl,
+  });
+
+  await loadBuiltinAiProviders();
+  const providerId = opts.provider || cfg.provider || 'pixverse';
+  const provider = getAiProvider(providerId);
+  if (!provider) throw new Error(`Unknown AI provider: ${providerId}`);
+
+  const model = opts.model || cfg.model || provider.models[0];
+  const quality = opts.quality || cfg.quality || '720p';
+  const duration = Number(opts.duration ?? cfg.default_duration) || 5;
+  const prompt = opts.prompt || (opts.profile ? profileToAiPrompt(opts.profile) : undefined);
+
+  const ok = await confirmAiCost({
+    provider: provider.title,
+    model,
+    duration,
+    quality,
+    yes: opts.yes,
+    quiet: opts.quiet,
+  });
+  if (!ok) throw new Error('Abgebrochen');
+
+  const job = createJob({
+    cwd,
+    type: 'ai-clip',
+    engine: 'ai',
+    provider: providerId,
+    image: opts.image,
+    preset: preset?.id,
+    model,
+    quality,
+    duration,
+    creditsHint: 1,
+    apiKeyPresent: hasPixVerseApiKey(undefined, cwd),
+  });
+
+  try {
+    const fresh = loadMotionConfig(cwd);
+    const result = await provider.imageToVideo({
+      cwd,
+      apiKey: opts.apiKey || fresh.api_key || process.env.PIXVERSE_API_KEY,
+      image: imageAbs,
+      prompt,
+      model,
+      quality,
+      duration,
+      outDir: opts.outDir || cfg.output_dir,
+      dryRun,
+    });
+    finishJob(job, {
+      status: 'done',
+      result,
+      engine: 'ai',
+      provider: providerId,
+      creditsHint: result.creditsHint || 1,
+      apiKeyPresent: true,
+    });
+    return { job, ...result, preset };
+  } catch (err) {
+    finishJob(job, { status: 'failed', error: safeErrorMessage(err) });
+    throw new Error(safeErrorMessage(err));
+  }
+}
+
+/**
+ * Batch atelier assets.
+ */
+export async function createAtelierBatch(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const dir = resolve(cwd, opts.dir || '.');
+  const images = listImageFiles(dir).slice(0, opts.count || 10);
+  const results = [];
+  for (const image of images) {
+    const r = await createMotionClip({
+      ...opts,
+      cwd,
+      image,
+      preset: opts.preset || 'atelier',
+      engine: opts.engine || 'local',
+      yes: opts.yes !== false,
+      quiet: true,
+    });
+    results.push(r);
+  }
+  const totalSec = results.reduce((n, r) => n + ((r.durationMs || 0) / 1000), 0);
+  return {
+    count: results.length,
+    images: images.length,
+    totalSec,
+    outDir: opts.outDir || './motion-output',
+    results,
+  };
+}
+
+export function listImageFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const st = statSync(dir);
+  if (st.isFile()) return [dir];
+  return readdirSync(dir)
+    .filter((f) => /\.(webp|png|jpe?g)$/i.test(f))
+    .sort()
+    .map((f) => join(dir, f));
+}
+
+/**
+ * AI or local transition between two images.
+ */
+export async function createMotionTransition(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  if ((opts.engine || 'local') !== 'ai') {
+    return createLocalTransition({
+      cwd,
+      imageA: opts.imageA,
+      imageB: opts.imageB,
+      duration: opts.duration,
+      outDir: opts.outDir,
+    });
+  }
+  const dryRun = resolveDryRun(opts);
+  const imageA = resolve(cwd, opts.imageA);
+  const imageB = resolve(cwd, opts.imageB);
+  assertMotionImageFile(imageA, 'Image A');
+  assertMotionImageFile(imageB, 'Image B');
+  await ensurePixVerseReady({
+    cwd,
+    yes: opts.yes,
+    quiet: opts.quiet,
+    json: opts.json,
+    dryRun,
+    openImpl: opts.openImpl,
+  });
+  await loadBuiltinAiProviders();
+  const cfg = loadMotionConfig(cwd);
+  const provider = getAiProvider(opts.provider || cfg.provider || 'pixverse');
+  if (!provider?.transition) throw new Error('Provider does not support transition');
+  const ok = await confirmAiCost({
+    provider: provider.title,
+    model: opts.model || cfg.model,
+    duration: opts.duration || cfg.default_duration,
+    quality: opts.quality || cfg.quality,
+    yes: opts.yes,
+  });
+  if (!ok) throw new Error('Abgebrochen');
+  return provider.transition({
+    cwd,
+    apiKey: cfg.api_key || process.env.PIXVERSE_API_KEY,
+    imageA,
+    imageB,
+    duration: opts.duration || cfg.default_duration,
+    model: opts.model || cfg.model,
+    quality: opts.quality || cfg.quality,
+    prompt: opts.prompt,
+    outDir: opts.outDir || cfg.output_dir,
+    dryRun,
+  });
+}
+
+/**
+ * Multi-frame sequence (AI multiTransition when possible).
+ */
+export async function createMotionSequence(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const dryRun = resolveDryRun(opts);
+  const frames = (opts.frames || []).map((f) => resolve(cwd, f));
+  if (frames.length < 2) throw new Error('sequence needs at least 2 frames');
+  frames.forEach((f, i) => assertMotionImageFile(f, `Frame ${i + 1}`));
+  await ensurePixVerseReady({
+    cwd,
+    yes: opts.yes,
+    quiet: opts.quiet,
+    json: opts.json,
+    dryRun,
+    openImpl: opts.openImpl,
+  });
+  await loadBuiltinAiProviders();
+  const cfg = loadMotionConfig(cwd);
+  const provider = getAiProvider(opts.provider || cfg.provider || 'pixverse');
+  if (!provider?.multiTransition) throw new Error('Provider does not support multiTransition');
+  const ok = await confirmAiCost({
+    provider: provider.title,
+    model: opts.model || cfg.model,
+    duration: opts.duration || cfg.default_duration,
+    quality: opts.quality || cfg.quality,
+    yes: opts.yes,
+  });
+  if (!ok) throw new Error('Abgebrochen');
+  return provider.multiTransition({
+    cwd,
+    apiKey: cfg.api_key || process.env.PIXVERSE_API_KEY,
+    images: frames,
+    duration: opts.duration || cfg.default_duration,
+    model: opts.model || cfg.model,
+    quality: opts.quality || cfg.quality,
+    prompt: opts.prompt,
+    outDir: opts.outDir || cfg.output_dir,
+    dryRun,
+  });
+}

package/packages/velinstyle-motion/src/jobs/cache.js

@@ -0,0 +1,30 @@
+/**
+ * Simple cache helpers under `.velin/motion/cache/`.
+ */
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { motionDir, ensureMotionDirs } from '../config.js';
+
+export function cacheKey(parts) {
+  return createHash('sha256').update(JSON.stringify(parts)).digest('hex').slice(0, 16);
+}
+
+export function cachePath(cwd, key, ext = '.bin') {
+  ensureMotionDirs(cwd);
+  const dir = join(motionDir(cwd), 'cache');
+  mkdirSync(dir, { recursive: true });
+  return join(dir, `${key}${ext}`);
+}
+
+export function readCache(cwd, key, ext) {
+  const p = cachePath(cwd, key, ext);
+  if (!existsSync(p)) return null;
+  return readFileSync(p);
+}
+
+export function writeCache(cwd, key, data, ext) {
+  const p = cachePath(cwd, key, ext);
+  writeFileSync(p, data);
+  return p;
+}

package/packages/velinstyle-motion/src/jobs/queue.js

@@ -0,0 +1,69 @@
+/**
+ * Job queue + manifests under `.velin/motion/jobs/`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { ensureMotionDirs, motionDir, redactSecrets } from '../config.js';
+import { recordUsage } from './usage.js';
+
+function nextId(cwd) {
+  const dir = join(motionDir(cwd), 'jobs');
+  mkdirSync(dir, { recursive: true });
+  const n = readdirSync(dir).filter((f) => f.endsWith('.json')).length + 1;
+  return `motion-${String(n).padStart(4, '0')}`;
+}
+
+/**
+ * @param {object} partial
+ */
+export function createJob(partial = {}) {
+  const cwd = partial.cwd || process.cwd();
+  ensureMotionDirs(cwd);
+  const id = partial.id || nextId(cwd);
+  const job = {
+    id,
+    status: 'pending',
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    ...partial,
+    cwd: undefined,
+  };
+  writeJob(cwd, job);
+  return { ...job, cwd };
+}
+
+export function writeJob(cwd, job) {
+  const dir = join(motionDir(cwd), 'jobs');
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${job.id}.json`);
+  const safe = redactSecrets({ ...job, updatedAt: new Date().toISOString() });
+  writeFileSync(path, `${JSON.stringify(safe, null, 2)}\n`);
+  return path;
+}
+
+export function finishJob(job, patch = {}) {
+  const cwd = job.cwd || process.cwd();
+  const next = {
+    ...job,
+    ...patch,
+    status: patch.status || 'done',
+    finishedAt: new Date().toISOString(),
+  };
+  writeJob(cwd, next);
+  recordUsage(cwd, next);
+  return next;
+}
+
+export function loadJob(cwd, id) {
+  const path = join(motionDir(cwd), 'jobs', `${id}.json`);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export function listJobs(cwd = process.cwd()) {
+  const dir = join(motionDir(cwd), 'jobs');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => JSON.parse(readFileSync(join(dir, f), 'utf8')));
+}

package/packages/velinstyle-motion/src/jobs/usage.js

@@ -0,0 +1,53 @@
+/**
+ * Aggregate motion usage stats from job manifests.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { motionDir, ensureMotionDirs } from '../config.js';
+import { listJobs } from './queue.js';
+
+function usagePath(cwd) {
+  return join(motionDir(cwd), 'usage.json');
+}
+
+export function recordUsage(cwd, job) {
+  ensureMotionDirs(cwd);
+  const path = usagePath(cwd);
+  let data = { entries: [] };
+  if (existsSync(path)) {
+    try {
+      data = JSON.parse(readFileSync(path, 'utf8'));
+    } catch { /* reset */ }
+  }
+  data.entries.push({
+    id: job.id,
+    at: job.finishedAt || new Date().toISOString(),
+    engine: job.engine || job.result?.engine || 'local',
+    provider: job.provider || null,
+    durationSec: job.result?.durationMs ? job.result.durationMs / 1000 : job.duration || null,
+    preset: job.preset || null,
+    creditsHint: job.creditsHint || (job.engine === 'ai' ? 1 : 0),
+  });
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+/**
+ * @param {string} [cwd]
+ */
+export function getUsageSummary(cwd = process.cwd()) {
+  const jobs = listJobs(cwd);
+  const now = Date.now();
+  const day = 86400000;
+  const today = jobs.filter((j) => j.finishedAt && now - Date.parse(j.finishedAt) < day);
+  const week = jobs.filter((j) => j.finishedAt && now - Date.parse(j.finishedAt) < 7 * day);
+  const aiToday = today.filter((j) => j.engine === 'ai' || j.provider);
+  const aiWeek = week.filter((j) => j.engine === 'ai' || j.provider);
+  const credits = aiWeek.reduce((n, j) => n + (j.creditsHint || 1), 0);
+
+  return {
+    today: { clips: today.length, ai: aiToday.length },
+    week: { clips: week.length, ai: aiWeek.length },
+    pixverse: { creditsUsedHint: credits },
+    totalJobs: jobs.length,
+  };
+}

package/packages/velinstyle-motion/src/local/effects.js

@@ -0,0 +1,139 @@
+/**
+ * Local clip effect definitions → CSS keyframes + animation meta.
+ */
+
+/** @typedef {{ name: string, keyframes: string, animation: string, extraCss?: string, extraHtml?: string }} LocalEffect */
+
+/** @type {Record<string, (opts: { durationMs: number }) => LocalEffect>} */
+const EFFECTS = {
+  zoom({ durationMs }) {
+    return {
+      name: 'zoom',
+      keyframes: `@keyframes velin-clip-zoom {
+  from { transform: scale(1); }
+  to { transform: scale(1.12); }
+}`,
+      animation: `velin-clip-zoom ${durationMs}ms ease-in-out both`,
+    };
+  },
+  pan({ durationMs }) {
+    return {
+      name: 'pan',
+      keyframes: `@keyframes velin-clip-pan {
+  from { transform: translateX(-4%) scale(1.08); }
+  to { transform: translateX(4%) scale(1.08); }
+}`,
+      animation: `velin-clip-pan ${durationMs}ms ease-in-out both`,
+    };
+  },
+  rotate({ durationMs }) {
+    return {
+      name: 'rotate',
+      keyframes: `@keyframes velin-clip-rotate {
+  from { transform: rotate(-4deg) scale(1.05); }
+  to { transform: rotate(4deg) scale(1.05); }
+}`,
+      animation: `velin-clip-rotate ${durationMs}ms ease-in-out both`,
+    };
+  },
+  fade({ durationMs }) {
+    return {
+      name: 'fade',
+      keyframes: `@keyframes velin-clip-fade {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}`,
+      animation: `velin-clip-fade ${Math.min(800, durationMs / 3)}ms ease-out both`,
+    };
+  },
+  intro({ durationMs }) {
+    return {
+      name: 'intro',
+      keyframes: `@keyframes velin-clip-intro {
+  from { opacity: 0; transform: translateY(12px) scale(0.98); }
+  to { opacity: 1; transform: translateY(0) scale(1); }
+}`,
+      animation: `velin-clip-intro ${Math.min(900, durationMs / 3)}ms cubic-bezier(0.22, 1, 0.36, 1) both`,
+    };
+  },
+  outro({ durationMs }) {
+    return {
+      name: 'outro',
+      keyframes: `@keyframes velin-clip-outro {
+  from { opacity: 1; transform: scale(1); }
+  to { opacity: 0; transform: scale(1.04); }
+}`,
+      animation: `velin-clip-outro ${Math.min(700, durationMs / 4)}ms ease-in ${Math.max(0, durationMs - 700)}ms both`,
+    };
+  },
+  particles({ durationMs }) {
+    return {
+      name: 'particles',
+      keyframes: `@keyframes velin-clip-particles {
+  from { opacity: 0.85; transform: scale(1.2); filter: blur(2px); }
+  to { opacity: 0; transform: scale(1); filter: blur(0); }
+}`,
+      animation: `velin-clip-particles ${Math.min(1200, durationMs / 2)}ms ease-out both`,
+      extraCss: `.velin-clip__particles {
+  position: absolute; inset: 0; pointer-events: none;
+  background:
+    radial-gradient(circle at 20% 30%, rgba(255,255,255,.55) 0 2px, transparent 3px),
+    radial-gradient(circle at 70% 40%, rgba(255,255,255,.4) 0 1.5px, transparent 3px),
+    radial-gradient(circle at 40% 75%, rgba(255,255,255,.5) 0 2px, transparent 3px),
+    radial-gradient(circle at 85% 70%, rgba(255,255,255,.35) 0 1px, transparent 2px);
+  animation: velin-clip-particles ${Math.min(1200, durationMs / 2)}ms ease-out both;
+}`,
+      extraHtml: '<div class="velin-clip__particles" aria-hidden="true"></div>',
+    };
+  },
+  'soft-zoom': (opts) => EFFECTS.zoom(opts),
+  transition({ durationMs }) {
+    return {
+      name: 'transition',
+      keyframes: `@keyframes velin-clip-transition {
+  0% { opacity: 0; transform: translateX(8%); }
+  20% { opacity: 1; transform: translateX(0); }
+  80% { opacity: 1; transform: translateX(0); }
+  100% { opacity: 0; transform: translateX(-8%); }
+}`,
+      animation: `velin-clip-transition ${durationMs}ms ease-in-out both`,
+    };
+  },
+};
+
+/**
+ * @param {string[]} effectIds
+ * @param {{ durationMs: number }} opts
+ */
+export function buildLocalEffects(effectIds, opts) {
+  const effects = [];
+  for (const id of effectIds || []) {
+    const key = id === 'ai' || id === 'mini-prompt' ? null : id;
+    if (!key || !EFFECTS[key]) continue;
+    effects.push(EFFECTS[key](opts));
+  }
+  if (!effects.length) effects.push(EFFECTS.zoom(opts));
+  return effects;
+}
+
+export function listLocalEffectIds() {
+  return Object.keys(EFFECTS).filter((k) => k !== 'soft-zoom');
+}
+
+/**
+ * Map a motion profile (from mini-prompt) to local effect ids.
+ * @param {{ direction?: string, phases?: string[], intensity?: string }} profile
+ */
+export function profileToLocalEffects(profile) {
+  const effects = ['fade'];
+  const phases = profile.phases || [];
+  if (phases.includes('zoom') || profile.direction === 'in') effects.push('zoom');
+  if (phases.includes('pan') || /left|right|rechts|links/i.test(profile.direction || '')) effects.push('pan');
+  if (phases.includes('rotate') || /rotat|dreh/i.test(JSON.stringify(profile))) effects.push('rotate');
+  if (phases.includes('particles') || phases.includes('explosion') || /explod|partikel/i.test(JSON.stringify(profile))) {
+    effects.push('particles');
+  }
+  if (phases.includes('outro') || phases.includes('exit')) effects.push('outro');
+  if (phases[0] === 'enter' || phases.includes('intro')) effects.unshift('intro');
+  return [...new Set(effects)];
+}

package/packages/velinstyle-motion/src/local/engine.js

@@ -0,0 +1,96 @@
+/**
+ * Local motion clip engine.
+ */
+import { resolve, basename } from 'path';
+import { getClipPreset, listClipPresets } from '../registry/presets.js';
+import { exportHtmlClip, exportTransitionHtml } from '../export/html-clip.js';
+import { profileToLocalEffects } from './effects.js';
+import { createJob, finishJob } from '../jobs/queue.js';
+import { assertMotionImageFile } from '../validate-image.js';
+
+/**
+ * @param {object} opts
+ * @param {string} opts.image
+ * @param {string} [opts.preset]
+ * @param {string} [opts.outDir]
+ * @param {number} [opts.duration]
+ * @param {object} [opts.profile]
+ * @param {string} [opts.cwd]
+ * @param {string[]} [opts.effects]
+ */
+export async function createLocalClip(opts) {
+  const image = resolve(opts.cwd || process.cwd(), opts.image);
+  assertMotionImageFile(image, 'Image');
+
+  const preset = getClipPreset(opts.preset || 'soft-zoom');
+  if (!preset) throw new Error(`Unknown clip preset: ${opts.preset}`);
+  if (preset.engine === 'ai') {
+    throw new Error(`Preset "${preset.id}" requires AI engine — use --ai / style ai`);
+  }
+
+  const durationMs = opts.duration
+    ? Math.round(Number(opts.duration) * 1000)
+    : preset.durationMs || 4000;
+
+  let effectIds = opts.effects || preset.effects || ['zoom'];
+  if (opts.profile) effectIds = profileToLocalEffects(opts.profile);
+
+  const job = createJob({
+    cwd: opts.cwd,
+    type: 'local-clip',
+    image,
+    preset: preset.id,
+    engine: 'local',
+  });
+
+  const outDir = resolve(opts.cwd || process.cwd(), opts.outDir || './motion-output');
+  const result = exportHtmlClip({
+    imagePath: image,
+    presetId: preset.id,
+    effectIds,
+    durationMs,
+    outDir,
+    jobId: job.id,
+  });
+
+  finishJob(job, { status: 'done', result });
+  return { job, ...result, preset };
+}
+
+/**
+ * @param {object} opts
+ */
+export async function createLocalTransition(opts) {
+  const cwd = opts.cwd || process.cwd();
+  const a = resolve(cwd, opts.imageA);
+  const b = resolve(cwd, opts.imageB);
+  assertMotionImageFile(a, 'Image A');
+  assertMotionImageFile(b, 'Image B');
+  const durationMs = opts.duration ? Math.round(Number(opts.duration) * 1000) : 5000;
+  const job = createJob({ cwd, type: 'local-transition', engine: 'local', images: [a, b] });
+  const outDir = resolve(cwd, opts.outDir || './motion-output');
+  const result = exportTransitionHtml({
+    imageA: a,
+    imageB: b,
+    durationMs,
+    outDir,
+    jobId: job.id,
+  });
+  finishJob(job, { status: 'done', result });
+  return { job, ...result };
+}
+
+/**
+ * Shortcut: effect name as preset-ish local clip.
+ */
+export async function createEffectClip(effect, image, opts = {}) {
+  return createLocalClip({
+    ...opts,
+    image,
+    preset: 'soft-zoom',
+    effects: [effect],
+  });
+}
+
+export { listClipPresets, getClipPreset };
+export { assertMotionImageFile, MOTION_IMAGE_EXTENSIONS } from '../validate-image.js';