videoclaw 3.0.0-alpha.1

package/src/video/scorecard.ts

@@ -0,0 +1,90 @@
+import type { VideoProjectStatusReport } from './status.js';
+import type { VideoProjectManifest } from './workspace.js';
+
+export interface VideoProjectScorecard {
+  score: number;
+  band: 'poor' | 'fair' | 'good' | 'excellent';
+  reasons: string[];
+}
+
+function clampScore(value: number): number {
+  return Math.max(0, Math.min(100, Math.round(value)));
+}
+
+function toBand(score: number): VideoProjectScorecard['band'] {
+  if (score >= 85) return 'excellent';
+  if (score >= 65) return 'good';
+  if (score >= 40) return 'fair';
+  return 'poor';
+}
+
+export function buildProjectScorecard(input: {
+  status: VideoProjectStatusReport;
+  manifest: VideoProjectManifest | null;
+}): VideoProjectScorecard {
+  let score = 0;
+  const reasons: string[] = [];
+
+  if (input.status.projectExists) {
+    score += 10;
+    reasons.push('Project workspace exists.');
+  }
+
+  if (input.manifest) {
+    score += 10;
+    reasons.push('Project manifest exists.');
+  }
+
+  const completedStageScore = input.status.completedStages.length * 15;
+  score += Math.min(completedStageScore, 75);
+  if (input.status.completedStages.length > 0) {
+    reasons.push(`${input.status.completedStages.length} stage(s) completed.`);
+  }
+
+  if (input.manifest?.owner) {
+    score += 5;
+    reasons.push('Owner assigned.');
+  }
+
+  if (input.manifest?.priority) {
+    score += 5;
+    reasons.push('Priority set.');
+  }
+
+  if (input.manifest?.dueDate) {
+    score += 5;
+    reasons.push('Due date set.');
+  }
+
+  if (input.status.artifactFiles.length > 0) {
+    score += Math.min(input.status.artifactFiles.length * 3, 15);
+    reasons.push(`${input.status.artifactFiles.length} canonical artifact(s) present.`);
+  }
+
+  if (input.status.checkpoints.some((checkpoint) => checkpoint.status === 'retry-required')) {
+    score -= 10;
+    reasons.push('Project is awaiting review revisions.');
+  }
+
+  if (input.status.checkpoints.some((checkpoint) => checkpoint.status === 'failed')) {
+    score -= 20;
+    reasons.push('Project has failed checkpoint(s).');
+  }
+
+  if (input.status.legacyImportSummary?.queueStatusMismatch) {
+    score -= 10;
+    reasons.push('Legacy import shows queue/output drift.');
+  }
+
+  if (input.status.legacyImportSummary?.nestedOutputRootDetected) {
+    score -= 5;
+    reasons.push('Legacy import shows nested output roots.');
+  }
+
+  const finalScore = clampScore(score);
+  return {
+    score: finalScore,
+    band: toBand(finalScore),
+    reasons,
+  };
+}

package/src/video/seedance-asset-library.ts

@@ -0,0 +1,259 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveProjectWorkspace } from './workspace.js';
+
+// xskill / NEX AI Asset Library client. Registers character reference images as
+// managed "Asset" avatars and returns their Asset:// URIs — the official
+// character-consistency mechanism for ark/seedance-2.0 (raw photoreal URLs in
+// reference_images trip the "real person" content filter and don't lock
+// identity; managed assets pass the filter and lock the character). The minted
+// Asset:// URIs flow straight into native-seedance's referencePaths, which
+// already routes Asset:// into reference_images. See the seedance-identity
+// memory + docs/CLI_REFERENCE.md.
+
+interface FetchLikeResponse {
+  ok: boolean;
+  status: number;
+  text(): Promise<string>;
+  json(): Promise<unknown>;
+}
+
+export type FetchLike = (input: string, init?: {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+}) => Promise<FetchLikeResponse>;
+
+export interface SeedanceAssetClientOptions {
+  apiKey: string;
+  baseUrl?: string;
+  fetchImpl?: FetchLike;
+  /** Delay between asset sync-status polls (ms). Default 1500. */
+  pollIntervalMs?: number;
+  /** Max sync polls before giving up. Default 30 (~45s at the default interval). */
+  maxSyncAttempts?: number;
+  /** Injectable sleep so tests don't wait in real time. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface RegisteredAsset {
+  name: string;
+  assetId: string;
+  assetUri: string;
+  intlAssetUri: string;
+  syncStatus: string;
+}
+
+interface AssetListItem {
+  asset_id?: string;
+  asset_uri?: string;
+  intl_asset_uri?: string;
+  sync_status?: string;
+}
+
+const DEFAULT_BASE_URL = 'https://api.xskill.ai';
+
+function resolved(options: SeedanceAssetClientOptions): {
+  apiKey: string;
+  baseUrl: string;
+  fetchImpl: FetchLike;
+  pollIntervalMs: number;
+  maxSyncAttempts: number;
+  sleep: (ms: number) => Promise<void>;
+} {
+  const apiKey = options.apiKey?.trim();
+  if (!apiKey) {
+    throw new Error('Seedance Asset Library requires an API key (SUTUI_API_KEY).');
+  }
+  return {
+    apiKey,
+    baseUrl: (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, ''),
+    fetchImpl: options.fetchImpl ?? (fetch as unknown as FetchLike),
+    pollIntervalMs: options.pollIntervalMs ?? 1500,
+    maxSyncAttempts: options.maxSyncAttempts ?? 30,
+    sleep: options.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms))),
+  };
+}
+
+function headers(apiKey: string): Record<string, string> {
+  return {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${apiKey}`,
+    // Mirror the web app so the request is treated as a first-party call.
+    Origin: 'https://www.xskill.ai',
+    Referer: 'https://www.xskill.ai/',
+  };
+}
+
+async function request(
+  fetchImpl: FetchLike,
+  method: string,
+  url: string,
+  apiKey: string,
+  body?: unknown,
+): Promise<unknown> {
+  const response = await fetchImpl(url, {
+    method,
+    headers: headers(apiKey),
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+  if (!response.ok) {
+    throw new Error(`Asset Library ${method} ${url} failed with HTTP ${response.status}: ${await response.text()}`);
+  }
+  return response.json();
+}
+
+function pick<T = unknown>(node: unknown, key: string): T | undefined {
+  if (node && typeof node === 'object') {
+    const record = node as Record<string, unknown>;
+    if (key in record) return record[key] as T;
+    if (record.data && typeof record.data === 'object' && key in (record.data as Record<string, unknown>)) {
+      return (record.data as Record<string, unknown>)[key] as T;
+    }
+  }
+  return undefined;
+}
+
+/** Find a group by exact name, or create it. Returns the group_id. */
+export async function ensureAssetGroup(
+  name: string,
+  options: SeedanceAssetClientOptions,
+): Promise<string> {
+  const { apiKey, baseUrl, fetchImpl } = resolved(options);
+  const listed = await request(fetchImpl, 'GET', `${baseUrl}/api/v3/assets/groups`, apiKey);
+  const items = (pick<unknown[]>(listed, 'items') ?? pick<unknown[]>(listed, 'groups') ?? []) as Array<Record<string, unknown>>;
+  const existing = items.find((group) => group.name === name);
+  if (existing && typeof existing.group_id === 'string') {
+    return existing.group_id;
+  }
+  const created = await request(fetchImpl, 'POST', `${baseUrl}/api/v3/assets/groups`, apiKey, {
+    name,
+    description: 'videoclaw character consistency assets',
+  });
+  const groupId = pick<string>(created, 'group_id');
+  if (!groupId) {
+    throw new Error(`Asset Library group create for "${name}" returned no group_id.`);
+  }
+  return groupId;
+}
+
+async function findAssetSync(
+  fetchImpl: FetchLike,
+  baseUrl: string,
+  apiKey: string,
+  assetId: string,
+): Promise<AssetListItem | undefined> {
+  const listed = await request(fetchImpl, 'GET', `${baseUrl}/api/v3/assets?page_size=600`, apiKey);
+  const items = (pick<unknown[]>(listed, 'items') ?? []) as AssetListItem[];
+  return items.find((item) => item.asset_id === assetId);
+}
+
+/**
+ * Register a public image URL as an Image asset under the group, then poll until
+ * it has synced to the international Ark profile (sync_status "active") — ark
+ * rejects assets that are still "processing". Returns the Asset:// URI.
+ */
+export async function registerImageAsset(
+  input: { groupId: string; name: string; imageUrl: string },
+  options: SeedanceAssetClientOptions,
+): Promise<RegisteredAsset> {
+  const { apiKey, baseUrl, fetchImpl, pollIntervalMs, maxSyncAttempts, sleep } = resolved(options);
+  const created = await request(fetchImpl, 'POST', `${baseUrl}/api/v3/assets`, apiKey, {
+    group_id: input.groupId,
+    name: input.name,
+    asset_type: 'Image',
+    image_url: input.imageUrl,
+    media_url: input.imageUrl,
+  });
+  const assetId = pick<string>(created, 'asset_id');
+  const assetUri = pick<string>(created, 'asset_uri');
+  if (!assetId || !assetUri) {
+    throw new Error(`Asset Library create for "${input.name}" returned no asset id/uri.`);
+  }
+  const intlAssetUri = pick<string>(created, 'intl_asset_uri') ?? assetUri.replace(/^Asset:\/\//, 'asset://');
+  let syncStatus = pick<string>(created, 'sync_status') ?? 'processing';
+
+  for (let attempt = 0; attempt < maxSyncAttempts && syncStatus !== 'active'; attempt += 1) {
+    await sleep(pollIntervalMs);
+    const found = await findAssetSync(fetchImpl, baseUrl, apiKey, assetId);
+    if (found?.sync_status) syncStatus = found.sync_status;
+  }
+  if (syncStatus !== 'active') {
+    throw new Error(`Asset "${input.name}" (${assetId}) did not reach sync_status "active" (last: ${syncStatus}).`);
+  }
+  return { name: input.name, assetId, assetUri, intlAssetUri, syncStatus };
+}
+
+/** One subject (character/product) entry in the seedance-assets.json artifact. */
+export interface SeedanceAssetEntry {
+  name: string;
+  assetId: string;
+  assetUri: string;
+  intlAssetUri: string;
+}
+
+export interface SeedanceAssetsArtifact {
+  schemaVersion: 1;
+  projectSlug: string;
+  groupName: string;
+  generatedAt: string;
+  assets: SeedanceAssetEntry[];
+}
+
+/**
+ * Result of reading `artifacts/seedance-assets.json`. `assetUriByName` is the
+ * lookup the execution layer wants: subject name -> Asset:// URI. `assets`
+ * preserves the raw entries (assetId, intlAssetUri) for callers that need them.
+ */
+export interface SeedanceAssetsLookup {
+  assets: SeedanceAssetEntry[];
+  assetUriByName: Map<string, string>;
+}
+
+/**
+ * Read `artifacts/seedance-assets.json` for a project. Returns an empty lookup
+ * (no entries, empty map) when the artifact is absent — Seedance generations
+ * degrade gracefully to description-only / unmanaged references rather than
+ * failing. A present-but-malformed file is NOT swallowed: JSON.parse surfaces
+ * the corruption, matching sibling readers like product-references.ts.
+ */
+export async function readSeedanceAssets(
+  workspaceRoot: string,
+  slug: string,
+): Promise<SeedanceAssetsLookup> {
+  const workspace = resolveProjectWorkspace(slug, workspaceRoot);
+  const path = join(workspace.artifactsDir, 'seedance-assets.json');
+  if (!existsSync(path)) {
+    return { assets: [], assetUriByName: new Map() };
+  }
+  const parsed = JSON.parse(await readFile(path, 'utf-8')) as Partial<SeedanceAssetsArtifact>;
+  const assets: SeedanceAssetEntry[] = Array.isArray(parsed.assets)
+    ? parsed.assets.map((asset) => ({
+        name: asset.name,
+        assetId: asset.assetId,
+        assetUri: asset.assetUri,
+        intlAssetUri: asset.intlAssetUri,
+      }))
+    : [];
+  const assetUriByName = new Map<string, string>();
+  for (const asset of assets) {
+    if (asset.name && asset.assetUri) {
+      assetUriByName.set(asset.name, asset.assetUri);
+    }
+  }
+  return { assets, assetUriByName };
+}
+
+/** High-level: ensure the group, register each character image, return the Asset:// URIs. */
+export async function registerCharacterAssets(
+  input: { groupName: string; characters: Array<{ name: string; imageUrl: string }> },
+  options: SeedanceAssetClientOptions,
+): Promise<RegisteredAsset[]> {
+  const groupId = await ensureAssetGroup(input.groupName, options);
+  const registered: RegisteredAsset[] = [];
+  for (const character of input.characters) {
+    registered.push(await registerImageAsset({ groupId, name: character.name, imageUrl: character.imageUrl }, options));
+  }
+  return registered;
+}

package/src/video/seedance-blocks.ts

@@ -0,0 +1,118 @@
+/**
+ * Joey-style Seedance block emitters: Subject Lock / Frame Map / Cross-Frame /
+ * Last Frame. Pure/deterministic — no I/O.
+ *
+ * WS0 binding probe (docs/superpowers/notes/ark-reference-order-result.md) is
+ * RESOLVED positional: per UseAPI docs + production ARK payloads (2026-05-30),
+ * all three gateways honor reference ORDER as the `@imageN` mapping, so `@imageN`
+ * slots are emitted as a HARD positional binding contract — the slot label is the
+ * reference-order key, not a descriptive hint.
+ */
+
+import { noFaceMorphTag } from './prompt-rules.js';
+
+/**
+ * WS0 reference-order binding mode. Resolved to `true`: positional binding is
+ * confirmed (UseAPI docs + production ARK payloads, 2026-05-30 — all three
+ * gateways honor reference ORDER as the `@imageN` mapping). `@imageN` is a hard
+ * positional reference-order contract, not guidance only.
+ */
+export const POSITIONAL_BINDING = true;
+
+export interface SubjectLockEntry {
+  label: string;   // visual descriptor, NOT a proper name
+  slot: string;    // e.g. '@image1'
+}
+
+export interface FrameMapEntry {
+  t: string;       // timecode range
+  beat: string;
+}
+
+/** FRAME MAP — ordered beats with timecodes. */
+export function frameMapBlock(entries: FrameMapEntry[]): string {
+  const lines = entries.map((e) => `  ${e.t}: ${e.beat}`).join('\n');
+  return `FRAME MAP:\n${lines}`;
+}
+
+/** SUBJECT LOCK — per-character identity binding to @imageN slots. */
+export function subjectLockBlock(entries: SubjectLockEntry[]): string {
+  if (entries.length === 0) {
+    return 'SUBJECT LOCK: preserve the primary subject identical across every frame.';
+  }
+  const lines = entries.map((e) => `  ${e.slot}: ${e.label} — lock this identity, do not alter.`).join('\n');
+  return `SUBJECT LOCK:\n${lines}`;
+}
+
+/** CROSS-FRAME RULES — identity/geography stability across cuts. */
+export function crossFrameBlock(): string {
+  return 'CROSS-FRAME RULES: face, hair, wardrobe, silhouette, palette, and geography stay identical across every cut; lighting logic and lens language established once and held.';
+}
+
+// ---------------------------------------------------------------------------
+// Text-discipline emitters (WS-C). The canonical multi-reference discipline
+// proven by the user's ARK payloads, factored as pure helpers so the same
+// wording is reused everywhere (and never drifts). All are opt-in: callers gate
+// them behind a flag so default output stays byte-stable.
+// ---------------------------------------------------------------------------
+
+/**
+ * Positional placements for {@link buildPositionalDescriptorLine}. Index 0 is
+ * the hero/centre, then the frame is read outward L/R. Matches the ARK habit of
+ * naming where each subject sits ("Center: …. Left: …. Right: ….").
+ */
+const POSITIONAL_PLACEMENTS = [
+  'Center',
+  'Left',
+  'Right',
+  'Far left',
+  'Far right',
+  'Background left',
+  'Background right',
+  'Background center',
+  'Foreground',
+] as const;
+
+const POSITIONAL_FALLBACK_DESCRIPTOR = 'as established in the reference image';
+
+/**
+ * Per-character POSITIONAL visual-descriptor line. Each subject is placed at a
+ * frame position (Center / Left / Right / …) carrying its VISUAL DESCRIPTOR
+ * (`entry.label`) — never a proper name. A missing descriptor falls back to a
+ * stable "as established in the reference image" so the slot still reads. Returns
+ * `''` for an empty list so single-subject / character-free scenes add nothing.
+ */
+export function buildPositionalDescriptorLine(entries: SubjectLockEntry[]): string {
+  if (entries.length === 0) return '';
+  return entries
+    .map((entry, index) => {
+      const placement = POSITIONAL_PLACEMENTS[index] ?? `Subject ${index + 1}`;
+      const descriptor = entry.label.trim() || POSITIONAL_FALLBACK_DESCRIPTOR;
+      return `${placement}: ${descriptor}.`;
+    })
+    .join(' ');
+}
+
+/**
+ * Explicit identity-lock / no-face-morph discipline line. Reuses the standing
+ * {@link noFaceMorphTag} rule (prompt-rules) so the "no face morphing" wording
+ * stays canonical across surfaces.
+ */
+export function buildIdentityLockLine(): string {
+  return `Keep each character identical to her reference image, ${noFaceMorphTag().split(',')[0]}.`;
+}
+
+/**
+ * Single-full-frame guard: forces the model to perform grid panels over time
+ * instead of reproducing a 3x3 collage as a moving split-screen. Shared between
+ * the grid-bearing packet variants and the opt-in text-discipline path so every
+ * multi-reference packet can carry the same guard text.
+ * See multi-shot-framework Anti-patterns ("Grid leakage").
+ */
+export const SINGLE_FULL_FRAME_GUARD =
+  'Output a single full-frame cinematic shot that fills the entire frame edge to edge — no 3x3 grid, no split-screen, no panel borders, no collage, no multi-panel montage, no contact sheet, no reference-card layout. The character reference sheets and storyboard grid are reference ONLY — never reproduce the multi-panel sheet, the character-sheet grid, or any panel layout in the video; read identity and motion from them and render one continuous live scene. Perform any grid panels as consecutive moments over time, never as one image.';
+
+/** LAST FRAME — closing composition lock + sanctioned text suppression. */
+export function lastFrameBlock(closing: string): string {
+  return `LAST FRAME: ${closing}. No on-screen text, no captions, no signage typography, no rendered text in the frame.`;
+}

package/src/video/seedance-chain-host.ts

@@ -0,0 +1,152 @@
+/**
+ * Hosting the auto-chain seed for the seedance-direct route.
+ *
+ * Auto-chain feeds scene N's rendered video into scene N+1 as a continuity
+ * reference. On runway/dreamina-useapi the transport uploads that local file
+ * itself, but **seedance-direct rejects local paths** — a reference must be a
+ * hosted HTTP(S) URL or an `Asset://` avatar URI. A whole-video host is also not
+ * available with the project's current credentials, so this module takes the
+ * proven seedance keyframe path instead: extract the prior scene's **last
+ * frame** as a still image, upload it to Go Bananas (which returns a public R2
+ * URL), and hand that hosted image back as the chain seed. native-seedance then
+ * routes a `.jpg` URL into `reference_images` (the image-to-video keyframe).
+ *
+ * Pure orchestration with injectable I/O deps (`extractLastFrame` + `uploadImage`)
+ * so the wiring is exercised fully offline; `defaultChainSeedHostDeps` supplies
+ * the real ffmpeg + Go Bananas implementations for production.
+ */
+
+import { mkdir, readFile } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+import { runFfmpeg } from './assemble/ffmpeg.js';
+
+const HOSTED_RE = /^https?:\/\//i;
+const VIDEO_EXTS = new Set(['.mp4', '.mov', '.webm', '.avi', '.mkv']);
+const GO_BANANAS_DEFAULT_BASE_URL = 'https://gobananasai.com/api';
+
+/** Injected I/O for {@link hostChainSeedAsImage} — real impls in {@link defaultChainSeedHostDeps}. */
+export interface ChainSeedHostDeps {
+  /** Extract the final frame of a local video into an image file (jpg). */
+  extractLastFrame: (videoPath: string, outImagePath: string) => Promise<void>;
+  /** Upload a local image file; resolve to its public hosted URL. */
+  uploadImage: (imagePath: string) => Promise<string>;
+}
+
+/**
+ * True when a chain-seed path is a LOCAL video that must be hosted before a
+ * seedance-direct submit. Already-hosted URLs, `Asset://` avatar URIs, and
+ * non-video paths are left alone (they submit as-is or are not chain seeds).
+ */
+export function chainSeedNeedsHosting(path: string): boolean {
+  if (!path) return false;
+  if (HOSTED_RE.test(path)) return false; // already a hosted URL
+  if (path.startsWith('Asset://')) return false; // managed avatar URI
+  const ext = (path.split('?')[0]?.match(/\.[^.\\/]+$/)?.[0] ?? '').toLowerCase();
+  return VIDEO_EXTS.has(ext);
+}
+
+/**
+ * Transform a local-video chain seed into a hosted last-frame image URL. Returns
+ * the path UNCHANGED when it doesn't need hosting (already a URL / `Asset://` /
+ * not a local video), so the caller can apply it unconditionally.
+ *
+ * On the hosting path it writes the extracted frame under `workDir` and returns
+ * the uploaded image's public URL.
+ */
+export async function hostChainSeedAsImage(
+  localVideoPath: string,
+  workDir: string,
+  deps: ChainSeedHostDeps,
+): Promise<string> {
+  if (!chainSeedNeedsHosting(localVideoPath)) return localVideoPath;
+  await mkdir(workDir, { recursive: true });
+  const stem = basename(localVideoPath, extname(localVideoPath));
+  const outImage = join(workDir, `${stem}-lastframe.jpg`);
+  await deps.extractLastFrame(localVideoPath, outImage);
+  return deps.uploadImage(outImage);
+}
+
+/** Extract the final frame of `videoPath` to `outImagePath` (jpg) via ffmpeg. */
+async function ffmpegExtractLastFrame(videoPath: string, outImagePath: string): Promise<void> {
+  // `-sseof -1` seeks to one second before EOF (an input option, so it precedes
+  // `-i`); `-update 1 -frames:v 1` then writes the single final decoded frame.
+  await runFfmpeg([
+    '-sseof', '-1',
+    '-i', videoPath,
+    '-update', '1',
+    '-frames:v', '1',
+    '-q:v', '2',
+    outImagePath,
+  ]);
+}
+
+/** Pull the public hosted URL out of a Go Bananas `/images/upload` response (shape-tolerant). */
+function extractPublicUrl(json: Record<string, unknown>): string | undefined {
+  const data = json.data as Record<string, unknown> | undefined;
+  const candidates = [
+    json.public_url,
+    json.publicUrl,
+    json.full_url,
+    json.fullUrl,
+    json.url,
+    json.image_url,
+    json.imageUrl,
+    data?.public_url,
+    data?.url,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.length > 0) return candidate;
+  }
+  return undefined;
+}
+
+/**
+ * Upload a local image to Go Bananas' multipart upload endpoint and return its
+ * public R2 URL. Mirrors the proven flow in `outpaint-keyframe.ts`:
+ *   POST {apiBase}/images/upload  (multipart/form-data, field `file`)
+ *     → { image_id, public_url, ... }
+ */
+async function goBananasUploadImage(
+  imagePath: string,
+  env: NodeJS.ProcessEnv,
+  fetcher: typeof fetch,
+): Promise<string> {
+  const apiKey = (env.GO_BANANAS_API_KEY ?? '').trim();
+  if (!apiKey) {
+    throw new Error('GO_BANANAS_API_KEY is required to host the seedance chain seed (last-frame image).');
+  }
+  const apiBase = (env.GO_BANANAS_API_URL ?? GO_BANANAS_DEFAULT_BASE_URL).trim();
+  const bytes = await readFile(imagePath);
+  const form = new FormData();
+  // Do NOT set Content-Type — FormData sets the multipart boundary itself.
+  form.append('file', new Blob([new Uint8Array(bytes)], { type: 'image/jpeg' }), basename(imagePath));
+
+  const res = await fetcher(`${apiBase}/images/upload`, {
+    method: 'POST',
+    headers: { 'X-API-Key': apiKey },
+    body: form,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '(no body)');
+    throw new Error(`go-bananas chain-seed upload HTTP ${res.status}: ${text.slice(0, 200)}`);
+  }
+  const json = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+  const url = extractPublicUrl(json);
+  if (!url) {
+    throw new Error(
+      `go-bananas chain-seed upload returned no public URL: ${JSON.stringify(json).slice(0, 200)}`,
+    );
+  }
+  return url;
+}
+
+/** Production deps: real ffmpeg last-frame extraction + Go Bananas image hosting. */
+export function defaultChainSeedHostDeps(
+  env: NodeJS.ProcessEnv = process.env,
+  fetcher: typeof fetch = fetch,
+): ChainSeedHostDeps {
+  return {
+    extractLastFrame: ffmpegExtractLastFrame,
+    uploadImage: (imagePath) => goBananasUploadImage(imagePath, env, fetcher),
+  };
+}