@birdapi/velinstyle 1.2.2 → 1.3.0

package/packages/velinstyle-motion/README.md

@@ -0,0 +1,81 @@
+# @birdapi/velinstyle-motion
+
+**Velin Motion Clip Pipeline** — image → short motion clip.
+
+- **Local** (default): CSS / Web Animations HTML clips — free, offline, reproducible
+- **AI** (optional): pluggable providers — first partner: **PixVerse** (credits + API key)
+
+This package is separate from the DOM Motion Design System (`@birdapi/velinstyle/motion` / `core/motion`).
+
+Ship with **`@birdapi/velinstyle@1.3.0`** (export `@birdapi/velinstyle/motion-clip`).
+
+## CLI (via VelinStyle)
+
+```bash
+velinstyle motion providers
+velinstyle motion setup pixverse
+velinstyle motion create atelier.webp
+velinstyle motion create hero.png --preset cinematic --yes
+velinstyle motion create logo.png --ai --yes   # needs PIXVERSE_API_KEY; dry: VELIN_MOTION_DRY_RUN=1
+velinstyle motion atelier ./assets --count 10 --preset atelier --yes
+velinstyle motion transition a.webp b.webp --yes
+velinstyle motion sequence 01.webp 02.webp 03.webp --provider pixverse --yes
+velinstyle motion usage
+```
+
+## PixVerse partner
+
+PixVerse is an **external** AI video platform. VelinStyle does not sell credits and does not host PixVerse.
+
+| | |
+|--|--|
+| Setup | `velinstyle motion setup pixverse` — affiliate-first (open / copy partner link · enter API key · abort) |
+| Signup | [VelinStyle partner link](https://motivaiprivatelimited.sjv.io/c/7581758/3811144/49478) (Impact) |
+| API docs | https://docs.platform.pixverse.ai/ |
+| Site guide | https://velinstyle.info/docs/guides/pixverse.html |
+
+There is **no** bare `platform.pixverse.ai` signup bypass in the CLI. Tracker blockers may block the affiliate open — use **copy partner link** then.
+
+## Config
+
+```
+.velin/motion/config.json
+.velin/motion/.env          # PIXVERSE_API_KEY=… (gitignored via .velin/)
+```
+
+```json
+{
+  "provider": "pixverse",
+  "api_key": "${PIXVERSE_API_KEY}",
+  "model": "v6",
+  "quality": "720p",
+  "default_duration": 5,
+  "output_dir": "./motion-output",
+  "pixverse": { "setup_completed": false }
+}
+```
+
+Never store plaintext API keys in `config.json`. Prefer `PIXVERSE_API_KEY` env or `.velin/motion/.env`. Keys are never logged, printed in `--json`, or written to job manifests.
+
+`--yes` + AI without a key → hard error (CI-safe). Affiliate browser opens only during explicit setup / first-time gate when `setup_completed` is false.
+
+**Image inputs:** non-empty `.webp` / `.png` / `.jpg` / `.jpeg` with valid raster magic bytes.
+
+## Programmatic
+
+```js
+import { createMotionClip, listClipPresets } from '@birdapi/velinstyle-motion';
+
+await createMotionClip({
+  image: 'atelier.webp',
+  preset: 'soft-zoom',
+  yes: true,
+});
+```
+
+## Providers
+
+Add another backend under `src/ai/providers/` and `registerAiProvider(...)`.  
+PixVerse implements `imageToVideo`, `transition`, `multiTransition` (capabilities-driven).
+
+Framework guide: [`docs/guides/velin-motion-clips.md`](../../docs/guides/velin-motion-clips.md)

package/packages/velinstyle-motion/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@birdapi/velinstyle-motion",
+  "version": "1.3.0",
+  "description": "Velin Motion Clip Pipeline — local image→clip engine + pluggable AI providers (PixVerse first)",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./presets": "./src/registry/presets.json"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SkyliteDesign/velinstyle.git",
+    "directory": "packages/velinstyle-motion"
+  },
+  "homepage": "https://velinstyle.info/docs/guides/velin-motion-clips.html",
+  "author": "SkyliteDesign",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "velinstyle",
+    "motion",
+    "animation",
+    "image-to-video",
+    "pixverse"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/packages/velinstyle-motion/src/ai/mini-prompt.js

@@ -0,0 +1,119 @@
+/**
+ * Mini-prompt → structured motion profile (not raw PixVerse prompts).
+ */
+
+/**
+ * @typedef {object} MotionProfile
+ * @property {string} direction
+ * @property {string[]} phases
+ * @property {string} intensity
+ * @property {string} [aiPrompt]
+ * @property {string} [label]
+ */
+
+const SUGGESTIONS = {
+  'rechts rein': [
+    { label: 'Rechts → Mitte', direction: 'right-in', phases: ['enter', 'hold'], intensity: 'soft' },
+    { label: 'Rechts → Mitte → Links', direction: 'right-in-left-out', phases: ['enter', 'hold', 'exit'], intensity: 'soft' },
+    { label: 'Rechts → Mitte → Explosion', direction: 'right-in', phases: ['enter', 'hold', 'explosion'], intensity: 'strong' },
+    { label: 'Rechts → Mitte → Partikel', direction: 'right-in', phases: ['enter', 'particles'], intensity: 'medium' },
+  ],
+  'links rein': [
+    { label: 'Links → Mitte', direction: 'left-in', phases: ['enter', 'hold'], intensity: 'soft' },
+    { label: 'Links → Mitte → Rechts', direction: 'left-in-right-out', phases: ['enter', 'hold', 'exit'], intensity: 'soft' },
+  ],
+};
+
+/**
+ * @param {string} text
+ * @returns {MotionProfile[]}
+ */
+export function suggestFromMiniPrompt(text) {
+  const t = (text || '').trim().toLowerCase();
+  if (!t) return [];
+
+  for (const [key, list] of Object.entries(SUGGESTIONS)) {
+    if (t.includes(key) || key.includes(t)) return list.map(enrichAiPrompt);
+  }
+
+  if (/dreh|rotat/.test(t) && /explod/.test(t)) {
+    return [
+      enrichAiPrompt({
+        label: 'Drehen + Explosion',
+        direction: 'center',
+        phases: ['rotate', 'explosion'],
+        intensity: 'strong',
+      }),
+      enrichAiPrompt({
+        label: 'Drehen + Partikel',
+        direction: 'center',
+        phases: ['rotate', 'particles'],
+        intensity: 'medium',
+      }),
+    ];
+  }
+
+  if (/zoom|näher|nah/.test(t)) {
+    return [
+      enrichAiPrompt({ label: 'Soft Zoom', direction: 'in', phases: ['zoom'], intensity: 'soft' }),
+      enrichAiPrompt({ label: 'Cinematic Zoom + Pan', direction: 'in', phases: ['zoom', 'pan'], intensity: 'medium' }),
+    ];
+  }
+
+  if (/partikel|particle/.test(t)) {
+    return [
+      enrichAiPrompt({ label: 'Particle Reveal', direction: 'center', phases: ['particles', 'fade'], intensity: 'medium' }),
+    ];
+  }
+
+  // Generic single profile from free text
+  return [
+    enrichAiPrompt({
+      label: `Profil: ${text.trim().slice(0, 48)}`,
+      direction: /rechts|right/.test(t) ? 'right-in' : /links|left/.test(t) ? 'left-in' : 'center',
+      phases: inferPhases(t),
+      intensity: /explod|stark|strong/.test(t) ? 'strong' : 'soft',
+      raw: text.trim(),
+    }),
+  ];
+}
+
+function inferPhases(t) {
+  const phases = [];
+  if (/rein|enter|einblend/.test(t)) phases.push('enter');
+  if (/zoom/.test(t)) phases.push('zoom');
+  if (/pan|schwenk/.test(t)) phases.push('pan');
+  if (/dreh|rotat/.test(t)) phases.push('rotate');
+  if (/partikel|particle/.test(t)) phases.push('particles');
+  if (/explod/.test(t)) phases.push('explosion');
+  if (/raus|ausblend|exit|links$/.test(t)) phases.push('exit');
+  if (!phases.length) phases.push('zoom', 'hold');
+  return phases;
+}
+
+function enrichAiPrompt(profile) {
+  const bits = [];
+  if (profile.phases?.includes('enter')) bits.push('subject enters frame smoothly');
+  if (profile.direction?.includes('right')) bits.push('motion from the right toward center');
+  if (profile.direction?.includes('left')) bits.push('motion from the left toward center');
+  if (profile.phases?.includes('zoom')) bits.push('gentle zoom');
+  if (profile.phases?.includes('pan')) bits.push('subtle camera pan');
+  if (profile.phases?.includes('rotate')) bits.push('slight rotation');
+  if (profile.phases?.includes('particles') || profile.phases?.includes('explosion')) {
+    bits.push('energetic particle burst, keep subject readable');
+  }
+  if (profile.phases?.includes('exit')) bits.push('exit opposite side with soft fade');
+  bits.push('cinematic, keep composition stable, no text overlay');
+  return {
+    ...profile,
+    aiPrompt: bits.join(', '),
+  };
+}
+
+/**
+ * Translate profile to PixVerse-oriented prompt string.
+ * @param {MotionProfile} profile
+ */
+export function profileToAiPrompt(profile) {
+  return profile.aiPrompt || enrichAiPrompt(profile).aiPrompt;
+}

package/packages/velinstyle-motion/src/ai/provider.js

@@ -0,0 +1,59 @@
+/**
+ * AiProvider interface — pluggable image/video backends.
+ * Capabilities are declared per provider; CLI queries them dynamically.
+ */
+
+/**
+ * @typedef {object} AiProvider
+ * @property {string} id
+ * @property {string} title
+ * @property {string[]} models
+ * @property {Set<string>|string[]} capabilities
+ * @property {(opts: object) => Promise<object>} imageToVideo
+ * @property {(opts: object) => Promise<object>} [transition]
+ * @property {(opts: object) => Promise<object>} [multiTransition]
+ * @property {(opts: object) => Promise<object>} [extend]
+ */
+
+/** @type {Map<string, AiProvider>} */
+const PROVIDERS = new Map();
+
+/**
+ * @param {AiProvider} provider
+ */
+export function registerAiProvider(provider) {
+  if (!provider?.id) throw new Error('registerAiProvider: id required');
+  PROVIDERS.set(provider.id, provider);
+  return provider.id;
+}
+
+export function getAiProvider(id) {
+  return PROVIDERS.get(id) || null;
+}
+
+export function listAiProviders() {
+  return [...PROVIDERS.values()].map((p) => ({
+    id: p.id,
+    title: p.title,
+    models: p.models,
+    capabilities: [...(p.capabilities || [])],
+  }));
+}
+
+export function providerHas(provider, capability) {
+  const caps = provider.capabilities;
+  if (!caps) return false;
+  if (caps instanceof Set) return caps.has(capability);
+  return caps.includes(capability);
+}
+
+/**
+ * Ensure built-in providers are loaded once.
+ */
+let loaded = false;
+export async function loadBuiltinAiProviders() {
+  if (loaded) return;
+  loaded = true;
+  const { createPixVerseProvider } = await import('./providers/pixverse.js');
+  registerAiProvider(createPixVerseProvider());
+}

package/packages/velinstyle-motion/src/ai/providers/pixverse-setup.js

@@ -0,0 +1,402 @@
+/**
+ * PixVerse provider setup — affiliate-first onboarding (Impact partner link).
+ * Never offer bare platform.pixverse.ai as a signup bypass.
+ * Browser opens only on explicit request. Never log API keys.
+ */
+import { randomUUID } from 'crypto';
+import { spawn, spawnSync } from 'child_process';
+import { createInterface } from 'readline';
+import {
+  ensureMotionDirs,
+  hasPixVerseApiKey,
+  isPixVerseSetupCompleted,
+  loadMotionConfig,
+  loadMotionDotEnv,
+  markPixVerseSetupCompleted,
+  savePixVerseApiKey,
+  safeErrorMessage,
+} from '../../config.js';
+
+/** Impact affiliate — only URL VelinStyle opens / copies for signup. */
+export const PIXVERSE_AFFILIATE_URL =
+  'https://motivaiprivatelimited.sjv.io/c/7581758/3811144/49478';
+
+/** @deprecated Kept for API docs references only — never use for signup attribution. */
+export const PIXVERSE_DIRECT_URL = 'https://platform.pixverse.ai/';
+
+export const PIXVERSE_DOCS_URL = 'https://docs.platform.pixverse.ai/';
+
+export const PIXVERSE_KEY_MISSING_HINT =
+  'PIXVERSE_API_KEY missing — run: velinstyle motion setup pixverse';
+
+export function formatPixVerseTrackerHint() {
+  return [
+    'Hinweis:',
+    'Wenn dein Browser den Tracking-Link blockiert, deaktiviere',
+    'für diesen Vorgang deinen Tracking-Blocker oder öffne den',
+    'kopierten Partnerlink in einem Browser ohne entsprechende Blockierung.',
+  ].join('\n');
+}
+
+/**
+ * Main visible CLI / docs block for PixVerse setup.
+ * @param {{ affiliateUrl?: string }} [opts]
+ */
+export function formatPixVerseSignupHelp(opts = {}) {
+  const affiliate = opts.affiliateUrl || PIXVERSE_AFFILIATE_URL;
+  return [
+    'PixVerse Setup',
+    '',
+    'VelinStyle verwendet PixVerse als AI-Provider.',
+    '',
+    'Um PixVerse über VelinStyle einzurichten, öffnet VelinStyle',
+    'deinen offiziellen PixVerse-Partnerlink.',
+    '',
+    affiliate,
+    '',
+    '[1] PixVerse über VelinStyle öffnen',
+    '[2] Partnerlink kopieren',
+    '[3] API-Key eingeben',
+    '[4] Abbrechen',
+    '',
+    formatPixVerseTrackerHint(),
+  ].join('\n');
+}
+
+/** @deprecated Use formatPixVerseSignupHelp / formatPixVerseOpenFailedHelp */
+export function formatPixVerseOpenAccountHelp(opts = {}) {
+  const affiliate = opts.affiliateUrl || PIXVERSE_AFFILIATE_URL;
+  return [
+    'PixVerse-Partnerlink:',
+    affiliate,
+    '',
+    formatPixVerseTrackerHint(),
+    '',
+    'Danach gib deinen API-Key hier ein:',
+  ].join('\n');
+}
+
+export function formatPixVerseOpenFailedHelp(opts = {}) {
+  const affiliate = opts.affiliateUrl || PIXVERSE_AFFILIATE_URL;
+  return [
+    'Der PixVerse-Partnerlink konnte in diesem Browser nicht',
+    'geöffnet werden.',
+    '',
+    'Grund:',
+    'Ein Tracking- oder Cookie-Blocker verhindert vermutlich',
+    'die Attribution.',
+    '',
+    'Partnerlink:',
+    affiliate,
+    '',
+    '[1] Erneut versuchen',
+    '[2] Link kopieren',
+    '[3] Abbrechen',
+  ].join('\n');
+}
+
+/**
+ * Open PixVerse signup — always the Impact affiliate URL (never bare platform.pixverse.ai).
+ * @returns {{ ok: boolean, url: string, error?: string }}
+ */
+export function openPixVerseSignup(url = PIXVERSE_AFFILIATE_URL, opts = {}) {
+  const target =
+    typeof url === 'string' && url.includes('motivaiprivatelimited.sjv.io')
+      ? url
+      : PIXVERSE_AFFILIATE_URL;
+  const spawnImpl = opts.spawnImpl || spawn;
+  const platform = process.platform;
+  try {
+    let child;
+    if (platform === 'win32') {
+      child = spawnImpl('cmd', ['/c', 'start', '', target], { detached: true, stdio: 'ignore' });
+    } else if (platform === 'darwin') {
+      child = spawnImpl('open', [target], { detached: true, stdio: 'ignore' });
+    } else {
+      child = spawnImpl('xdg-open', [target], { detached: true, stdio: 'ignore' });
+    }
+    if (child && typeof child.unref === 'function') child.unref();
+    if (opts.forceFail) {
+      return { ok: false, url: target, error: 'forced open failure' };
+    }
+    return { ok: true, url: target };
+  } catch (err) {
+    return { ok: false, url: target, error: safeErrorMessage(err) };
+  }
+}
+
+/** Assert helper for CLI/docs — always prefer affiliate over bare platform URL. */
+export function pixVerseSignupUrl(url) {
+  if (typeof url === 'string' && url.includes('motivaiprivatelimited.sjv.io')) return url;
+  return PIXVERSE_AFFILIATE_URL;
+}
+
+/**
+ * Copy the official partner link to the clipboard (affiliate only).
+ * @returns {{ ok: boolean, url: string, method?: string }}
+ */
+export function copyPixVersePartnerLink(opts = {}) {
+  const url = opts.url || PIXVERSE_AFFILIATE_URL;
+  const target = pixVerseSignupUrl(url);
+  const platform = process.platform;
+  try {
+    if (opts.copyImpl) {
+      opts.copyImpl(target);
+      return { ok: true, url: target, method: 'custom' };
+    }
+    if (platform === 'win32') {
+      const r = spawnSync(
+        'powershell',
+        ['-NoProfile', '-Command', `Set-Clipboard -Value @'\n${target}\n'@`],
+        { windowsHide: true, encoding: 'utf8' },
+      );
+      if (r.error || (r.status !== 0 && r.status != null)) {
+        return { ok: false, url: target };
+      }
+      return { ok: true, url: target, method: 'Set-Clipboard' };
+    }
+    if (platform === 'darwin') {
+      const r = spawnSync('pbcopy', [], { input: target, encoding: 'utf8' });
+      if (r.error || (r.status !== 0 && r.status != null)) {
+        return { ok: false, url: target };
+      }
+      return { ok: true, url: target, method: 'pbcopy' };
+    }
+    let r = spawnSync('wl-copy', [], { input: target, encoding: 'utf8' });
+    if (!r.error && (r.status === 0 || r.status == null)) {
+      return { ok: true, url: target, method: 'wl-copy' };
+    }
+    r = spawnSync('xclip', ['-selection', 'clipboard'], { input: target, encoding: 'utf8' });
+    if (!r.error && (r.status === 0 || r.status == null)) {
+      return { ok: true, url: target, method: 'xclip' };
+    }
+    return { ok: false, url: target };
+  } catch {
+    return { ok: false, url: target };
+  }
+}
+
+function ask(rl, q) {
+  return new Promise((resolve) => {
+    rl.question(q, resolve);
+  });
+}
+
+function writePartnerCopied(result) {
+  if (result.ok) {
+    process.stdout.write(`\nPartnerlink kopiert:\n${result.url}\n`);
+  } else {
+    process.stdout.write(
+      `\nPartnerlink (manuell kopieren):\n${result.url}\n`,
+    );
+  }
+  process.stdout.write(`\n${formatPixVerseTrackerHint()}\n`);
+}
+
+/**
+ * Open partner link; on technical failure offer retry / copy / abort (no direct bypass).
+ * @returns {Promise<'opened'|'copied'|'aborted'>}
+ */
+export async function runPixVersePartnerOpenFlow(opts = {}) {
+  const rl = opts.rl;
+  if (!rl) throw new Error('runPixVersePartnerOpenFlow requires opts.rl');
+  const openImpl = opts.openImpl || openPixVerseSignup;
+  const copyImpl = opts.copyImpl;
+
+  async function attemptOpen() {
+    const result = openImpl(PIXVERSE_AFFILIATE_URL, {
+      spawnImpl: opts.spawnImpl,
+      forceFail: opts.forceFail,
+    });
+    const normalized =
+      result && typeof result === 'object' && 'url' in result
+        ? result
+        : { ok: true, url: typeof result === 'string' ? result : PIXVERSE_AFFILIATE_URL };
+
+    if (normalized.ok) {
+      process.stdout.write(`\nPartnerlink geöffnet:\n${normalized.url}\n`);
+      process.stdout.write(`\n${formatPixVerseTrackerHint()}\n`);
+      process.stdout.write(`Docs: ${PIXVERSE_DOCS_URL}\n`);
+      return 'opened';
+    }
+
+    process.stdout.write(`\n${formatPixVerseOpenFailedHelp({ affiliateUrl: normalized.url })}\n`);
+    const choice = (await ask(rl, 'Auswahl [1/2/3]: ')).trim();
+    if (choice === '1' || choice === '') {
+      return attemptOpen();
+    }
+    if (choice === '2') {
+      writePartnerCopied(copyPixVersePartnerLink({ copyImpl }));
+      return 'copied';
+    }
+    return 'aborted';
+  }
+
+  return attemptOpen();
+}
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]
+ * @param {import('readline').Interface} [opts.rl]
+ * @param {boolean} [opts.save]
+ */
+export async function promptAndSaveApiKey(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  ensureMotionDirs(cwd);
+  const rl = opts.rl || createInterface({ input: process.stdin, output: process.stdout });
+  const owned = !opts.rl;
+  try {
+    process.stdout.write('\nPixVerse API-Key:\n');
+    const raw = await ask(rl, '> ');
+    const key = String(raw || '').trim();
+    if (!key) throw new Error('Kein API-Key eingegeben');
+
+    let doSave = opts.save;
+    if (doSave == null) {
+      const ans = await ask(rl, 'API-Key speichern? [J/n] ');
+      const a = (ans || 'j').trim().toLowerCase();
+      doSave = a === '' || a === 'j' || a === 'y' || a === 'ja' || a === 'yes';
+    }
+    if (doSave) {
+      savePixVerseApiKey(key, cwd);
+    } else {
+      process.env.PIXVERSE_API_KEY = key;
+    }
+    return { saved: Boolean(doSave), present: true };
+  } finally {
+    if (owned) rl.close();
+  }
+}
+
+/**
+ * Lightweight connection check — never includes the key in errors/results.
+ * @param {object} [opts]
+ */
+export async function testPixVerseConnection(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  loadMotionDotEnv(cwd);
+  const key = process.env.PIXVERSE_API_KEY || loadMotionConfig(cwd).api_key;
+  if (!key) {
+    return { ok: false, reason: PIXVERSE_KEY_MISSING_HINT };
+  }
+  if (opts.skipNetwork || process.env.VELIN_MOTION_DRY_RUN === '1') {
+    return { ok: true, dryCheck: true, apiKeyPresent: true };
+  }
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  if (!fetchImpl) {
+    return { ok: true, dryCheck: true, apiKeyPresent: true, note: 'fetch unavailable — key format accepted' };
+  }
+  try {
+    const res = await fetchImpl('https://app-api.pixverse.ai/openapi/v2/video/list', {
+      method: 'GET',
+      headers: {
+        'API-KEY': key,
+        'Ai-trace-id': randomUUID(),
+      },
+    });
+    if (res.status === 401 || res.status === 403) {
+      return { ok: false, reason: 'PixVerse rejected the API key (HTTP auth error)' };
+    }
+    return { ok: true, apiKeyPresent: true, httpStatus: res.status };
+  } catch (err) {
+    return {
+      ok: false,
+      reason: `Network error during PixVerse check: ${safeErrorMessage(err)}`,
+    };
+  }
+}
+
+/**
+ * Interactive PixVerse setup — affiliate-first menu (open / copy / key / abort).
+ * @param {object} [opts]
+ */
+export async function runPixVerseSetup(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  ensureMotionDirs(cwd);
+  loadMotionDotEnv(cwd);
+
+  if (opts.yes) {
+    if (!hasPixVerseApiKey(undefined, cwd)) {
+      throw new Error(PIXVERSE_KEY_MISSING_HINT);
+    }
+    markPixVerseSetupCompleted(cwd);
+    const test = await testPixVerseConnection({
+      cwd,
+      skipNetwork: opts.skipNetwork !== false,
+      fetchImpl: opts.fetchImpl,
+    });
+    return {
+      provider: 'pixverse',
+      setup_completed: true,
+      apiKeyPresent: true,
+      test,
+    };
+  }
+
+  if (!process.stdin.isTTY) {
+    throw new Error(PIXVERSE_KEY_MISSING_HINT);
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    process.stdout.write(`\nVelinStyle Motion\n\n${formatPixVerseSignupHelp()}\n\n`);
+    const choice = (await ask(rl, 'Auswahl [1/2/3/4]: ')).trim();
+
+    let openedBrowser = false;
+    if (choice === '4' || choice.toLowerCase() === 'q' || choice.toLowerCase() === 'c') {
+      throw new Error('Abgebrochen');
+    }
+    if (choice === '1' || choice === '') {
+      const outcome = await runPixVersePartnerOpenFlow({
+        rl,
+        openImpl: opts.openImpl,
+        spawnImpl: opts.spawnImpl,
+        copyImpl: opts.copyImpl,
+        forceFail: opts.forceFail,
+      });
+      if (outcome === 'aborted') throw new Error('Abgebrochen');
+      openedBrowser = outcome === 'opened';
+      process.stdout.write(
+        '\nRichte den API-Zugang im PixVerse-Dashboard ein, dann füge den Key hier ein.\n',
+      );
+    } else if (choice === '2') {
+      writePartnerCopied(copyPixVersePartnerLink({ copyImpl: opts.copyImpl }));
+      process.stdout.write(
+        '\nÖffne den kopierten Partnerlink, richte den API-Zugang ein, dann Key hier einfügen.\n',
+      );
+    } else if (choice === '3') {
+      process.stdout.write(
+        '\nAPI-Key aus dem PixVerse-Dashboard einfügen (Env / .velin/motion/.env).\n',
+      );
+    } else {
+      throw new Error('Abgebrochen');
+    }
+
+    await promptAndSaveApiKey({ cwd, rl });
+
+    const test = await testPixVerseConnection({
+      cwd,
+      skipNetwork: opts.skipNetwork,
+      fetchImpl: opts.fetchImpl,
+    });
+    if (!test.ok && !test.dryCheck) {
+      process.stdout.write(`\nVerbindung: ${test.reason}\n`);
+      process.stdout.write('(Key wurde gespeichert — du kannst später erneut testen.)\n');
+    } else {
+      process.stdout.write('\nVerbindung: OK (oder Dry-Check)\n');
+    }
+
+    markPixVerseSetupCompleted(cwd);
+    return {
+      provider: 'pixverse',
+      setup_completed: true,
+      apiKeyPresent: true,
+      openedBrowser,
+      test: { ok: test.ok, dryCheck: test.dryCheck, apiKeyPresent: true },
+    };
+  } finally {
+    rl.close();
+  }
+}