@hraness/slopcamera 3.3.3 → 3.3.5

package/apps/desktop/cli/directing-blob.ts

@@ -18,7 +18,7 @@ import { resolveVerifiedProjectMedia } from "./project-media-integrity";
 // put.ts, del.ts, and signed-token.ts in https://github.com/vercel/storage.
 // The SDK's network retry/environment overrides are not part of this adapter.
 const API = "https://vercel.com/api/blob";
-const LIMITS = { imageBytes: 30 * 1024 * 1024, entries: 2, receiptBytes: 64 * 1024, responseBytes: 32 * 1024, requestMs: 60_000, cleanupMs: 120_000, accessMs: 15 * 60_000 } as const;
+const LIMITS = { imageBytes: 30 * 1024 * 1024, videoBytes: 256 * 1024 * 1024, entries: 8, receiptBytes: 64 * 1024, responseBytes: 32 * 1024, requestMs: 60_000, uploadMs: 15 * 60_000, cleanupMs: 120_000, accessMs: 15 * 60_000 } as const;
 const RECEIPT = "receipt.json";
 const NOTICE = "Private reference hosting uses Vercel Blob operations, storage, and transfer billed separately from the Gateway generation budget. Expiring model access does not delete the stored object.";
 const IdSchema = z.string().regex(/^direct_[a-z][a-z0-9_-]{0,63}$/u);
@@ -26,10 +26,15 @@ const TakeSchema = z.string().regex(/^take_[a-z][a-z0-9_-]{0,63}$/u);
 const StoreSchema = z.string().regex(/^[A-Za-z0-9]{1,64}$/u);
 const TimeSchema = z.number().int().safe().positive();
 const EtagSchema = z.string().min(1).max(256).regex(/^[\x21-\x7e]+$/u);
-const SourceSchema = GatewayMediaSourceReferenceSchema.refine(source => ["image/png", "image/jpeg", "image/webp"].includes(source.mediaType) && source.bytes <= LIMITS.imageBytes, "Hosted directing references must be PNG, JPEG, or WebP images at most 30 MiB.");
+const SourceSchema = GatewayMediaSourceReferenceSchema.refine(source =>
+  (["image/png", "image/jpeg", "image/webp"].includes(source.mediaType) && source.bytes <= LIMITS.imageBytes)
+  || (["video/mp4", "video/quicktime"].includes(source.mediaType) && source.bytes <= LIMITS.videoBytes), "Hosted directing references must be PNG, JPEG, or WebP images at most 30 MiB, or MP4/QuickTime video at most 256 MiB.");
+function sourceExtension(mediaType: string): string {
+  return mediaType === "image/jpeg" ? "jpg" : mediaType === "video/quicktime" ? "mov" : mediaType.slice(6);
+}
 const EntrySchema = z.strictObject({
   source: SourceSchema,
-  pathname: z.string().regex(/^slopcamera\/directing\/[a-f0-9]{32}\/[01]-[a-f0-9]{64}\.(?:png|jpg|webp)$/u),
+  pathname: z.string().regex(/^slopcamera\/directing\/[a-f0-9]{32}\/[0-7]-[a-f0-9]{64}\.(?:png|jpg|webp|mp4|mov)$/u),
   putStartedAt: TimeSchema,
   putCompletedAt: TimeSchema.optional(),
   etag: EtagSchema.optional(),
@@ -52,7 +57,7 @@ export const DirectingBlobReceiptSchema = z.strictObject({
   entries: z.array(EntrySchema).max(LIMITS.entries),
 }).superRefine((receipt, context) => {
   for (const [index, entry] of receipt.entries.entries()) {
-    const extension = entry.source.mediaType === "image/jpeg" ? "jpg" : entry.source.mediaType.slice(6);
+    const extension = sourceExtension(entry.source.mediaType);
     if (entry.pathname !== `slopcamera/directing/${receipt.namespace}/${index}-${entry.source.sha256}.${extension}`) context.addIssue({ code: "custom", message: "A hosted object must bind this session's exact private namespace and source bytes." });
   }
 });
@@ -161,12 +166,12 @@ export async function createDirectingBlobSession(options: DirectingBlobOptions):
       const save = async () => { await fs.writeTextAtomicGuarded!(RECEIPT, `${canonicalJson(DirectingBlobReceiptSchema.parse(receipt))}\n`, lease.assertOwned); };
       return await execute(receipt, save, lease.assertOwned);
     });
-  const api = async (receipt: DirectingBlobReceipt, pathname: string, method: "GET" | "PUT" | "POST", body: string | Uint8Array | undefined, headers: Record<string, string>, signal: AbortSignal, assertOwned: () => Promise<void>): Promise<{ status: number; data: Uint8Array }> => {
+  const api = async (receipt: DirectingBlobReceipt, pathname: string, method: "GET" | "PUT" | "POST", body: string | Uint8Array | undefined, headers: Record<string, string>, signal: AbortSignal, assertOwned: () => Promise<void>, timeoutMs: number = LIMITS.requestMs): Promise<{ status: number; data: Uint8Array }> => {
     const auth = credentials(options.environment);
     if (auth.storeId !== receipt.storeId) failure("Blob credentials don't match the retained store.", "authorization-required");
     await assertOwned();
     signal.throwIfAborted();
-    const bounded = AbortSignal.any([signal, AbortSignal.timeout(LIMITS.requestMs)]);
+    const bounded = AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]);
     const response = await request(`${API}${pathname}`, { method, redirect: "error", signal: bounded,
       headers: { authorization: `Bearer ${auth.token}`, "x-vercel-blob-store-id": auth.storeId, "x-api-version": "12", "x-api-blob-request-id": `${auth.storeId}:${randomUUID()}`, "x-api-blob-request-attempt": "0", ...headers },
       ...(body === undefined ? {} : { body: typeof body === "string" ? body : Buffer.from(body) }),
@@ -189,7 +194,7 @@ export async function createDirectingBlobSession(options: DirectingBlobOptions):
   };
   const verifyGet = async (receipt: DirectingBlobReceipt, entry: Entry, url: string, signal: AbortSignal): Promise<{ found: false } | { found: true; etag: string }> => {
     exactPrivateUrl(url, receipt.storeId, entry.pathname, true);
-    const bounded = AbortSignal.any([signal, AbortSignal.timeout(LIMITS.requestMs)]);
+    const bounded = AbortSignal.any([signal, AbortSignal.timeout(LIMITS.uploadMs)]);
     const response = await request(url, { method: "GET", redirect: "error", signal: bounded, headers: { "cache-control": "no-cache" } });
     if (response.status === 404) { await response.body?.cancel(); return { found: false }; }
     if (response.status !== 200) { await response.body?.cancel(); failure("Private hosted reference could not be verified."); }
@@ -212,9 +217,9 @@ export async function createDirectingBlobSession(options: DirectingBlobOptions):
     inspect: read,
     resolveSourceUrl: async (input, data, signal) => {
       const source = SourceSchema.parse(input);
-      if (!(data instanceof Uint8Array) || data.length !== source.bytes) failure("Reference hosting requires the exact retained image bytes.", "invalid-data");
+      if (!(data instanceof Uint8Array) || data.length !== source.bytes) failure("Reference hosting requires the exact retained reference bytes.", "invalid-data");
       const uploadBytes = new Uint8Array(data);
-      if (createHash("sha256").update(uploadBytes).digest("hex") !== source.sha256 || !gatewayMediaBytesMatchType(uploadBytes, source.mediaType)) failure("Reference hosting requires the exact retained image bytes.", "invalid-data");
+      if (createHash("sha256").update(uploadBytes).digest("hex") !== source.sha256 || !gatewayMediaBytesMatchType(uploadBytes, source.mediaType)) failure("Reference hosting requires the exact retained reference bytes.", "invalid-data");
       await resolveVerifiedProjectMedia({ repositoryRoot: application.paths.repositoryRoot, path: source.path, expected: source, label: "Directing hosted reference" });
       const activeSignal = AbortSignal.any([options.signal, signal]);
       return await mutate(async (receipt, save, assertOwned) => {
@@ -222,14 +227,14 @@ export async function createDirectingBlobSession(options: DirectingBlobOptions):
         if (receipt.closedAt !== undefined) failure("This reference-hosting session is closed; use a new take for another generation.", "conflict");
         let entry = receipt.entries.find(value => sourceIdentity(value.source) === sourceIdentity(source));
         if (entry === undefined) {
-          if (receipt.entries.length >= LIMITS.entries) failure("One directing take may host at most two exact image references.", "invalid-data");
-          const extension = source.mediaType === "image/jpeg" ? "jpg" : source.mediaType.slice(6);
+          if (receipt.entries.length >= LIMITS.entries) failure("One directing take may host at most eight exact media references.", "invalid-data");
+          const extension = sourceExtension(source.mediaType);
           entry = { source, pathname: `slopcamera/directing/${receipt.namespace}/${receipt.entries.length}-${source.sha256}.${extension}`, putStartedAt: now(), cleanup: "pending", failures: [] };
           receipt.entries.push(entry);
           await save(); // Durable exact upload intent precedes the only PUT.
           try {
             const uploaded = await api(receipt, `/?${new URLSearchParams({ pathname: entry.pathname })}`, "PUT", uploadBytes,
-              { "content-type": source.mediaType, "x-content-type": source.mediaType, "x-vercel-blob-access": "private", "x-add-random-suffix": "0", "x-allow-overwrite": "0", "x-cache-control-max-age": "60" }, activeSignal, assertOwned);
+              { "content-type": source.mediaType, "x-content-type": source.mediaType, "x-vercel-blob-access": "private", "x-add-random-suffix": "0", "x-allow-overwrite": "0", "x-cache-control-max-age": "60" }, activeSignal, assertOwned, LIMITS.uploadMs);
             if (uploaded.status < 200 || uploaded.status > 299) failure("Private reference upload did not complete.");
             const result = z.object({ url: z.string().max(2048), pathname: z.string().max(512), contentType: z.string().max(128), etag: EtagSchema }).parse(JSON.parse(new TextDecoder().decode(uploaded.data)) as unknown);
             exactPrivateUrl(result.url, receipt.storeId, entry.pathname, false);

package/apps/desktop/cli/directing-media.ts

@@ -20,7 +20,7 @@ import { withMutationLock } from "./mutation-lock";
 import { ensurePhysicalPrivateDirectoryWithin } from "./paths";
 import { resolveVerifiedProjectMedia } from "./project-media-integrity";
 
-const LIMITS = { videoBytes: 512 * 1024 * 1024, imageBytes: 30 * 1024 * 1024, probeBytes: 8 * 1024 * 1024, dimension: 4096, frames: 4000, durationUs: 60_000_000 } as const;
+const LIMITS = { videoBytes: 512 * 1024 * 1024, imageBytes: 30 * 1024 * 1024, referenceBytes: 256 * 1024 * 1024, probeBytes: 8 * 1024 * 1024, dimension: 4096, frames: 4000, durationUs: 60_000_000 } as const;
 const INPUT_ARGUMENTS = ["-protocol_whitelist", "file", "-format_whitelist", "mov", "-enable_drefs", "0", "-use_absolute_path", "0", "-max_pixels", String(LIMITS.dimension ** 2), "-threads", "2"] as const;
 const artifactSchema = z.strictObject({ path: RepositoryRelativePathSchema, bytes: z.number().int().safe().positive(), sha256: Sha256Schema });
 const endpointSchema = DirectingEndpointSchema.refine(endpoint => endpoint.frameIndex < LIMITS.frames, "Directing endpoint exceeds the 4000-frame media bound.");
@@ -226,15 +226,25 @@ async function retainVideo(application: ApplicationContext, input: GatewayMediaS
   return GatewayMediaSourceReferenceSchema.parse({ ...artifact, mediaType: source.mediaType });
 }
 
-/** Imports exactly the caller-named still; never uploads it or reads neighboring files. */
+/** Imports exactly the caller-named still or clip; never uploads it or reads neighboring files. */
 export async function importDirectingAnchor(application: ApplicationContext, path: string, signal: AbortSignal): Promise<GatewayMediaSourceReference> {
   await active(application, signal);
   const resolved = resolve(application.paths.repositoryRoot, path);
   if (await realpath(dirname(resolved)) !== dirname(resolved)) throw new CliError("unsafe-path", "Directing anchors require physical parent directories.");
-  const bytes = await fileBytes(resolved, LIMITS.imageBytes, signal);
+  const bytes = await fileBytes(resolved, LIMITS.referenceBytes, signal);
+  const brand = bytes.length >= 12 && Buffer.from(bytes.subarray(4, 8)).toString("ascii") === "ftyp" ? Buffer.from(bytes.subarray(8, 12)).toString("ascii") : undefined;
+  if (brand === "qt  " || brand !== undefined && /^(?:isom|iso2|iso5|iso6|mp41|mp42|avc1|dash|mmp4|M4V )$/u.test(brand)) {
+    const mediaType = brand === "qt  " ? "video/quicktime" : "video/mp4";
+    const artifact = await publishBytes(application, bytes, mediaType === "video/quicktime" ? "mov" : "mp4", signal);
+    const provisional = GatewayMediaSourceReferenceSchema.parse({ ...artifact, mediaType });
+    const ffprobe = await capability(application, "ffprobe");
+    const probed = await probeVideo(application, provisional, ffprobe.command, signal);
+    return GatewayMediaSourceReferenceSchema.parse({ ...provisional, facts: { durationSeconds: probed.media.durationUs / 1_000_000, width: probed.stream.width, height: probed.stream.height } });
+  }
+  if (bytes.length > LIMITS.imageBytes) fail("Directing anchors require a single unrotated PNG, JPEG, or WebP image no larger than 30 MiB.");
   const metadata = await sharp(bytes, { limitInputPixels: LIMITS.dimension ** 2, failOn: "error", animated: true }).metadata();
   const extension = metadata.format === "jpeg" ? "jpg" : metadata.format;
-  if (!extension || !["png", "jpg", "webp"].includes(extension) || metadata.pages !== undefined && metadata.pages !== 1 || !metadata.width || !metadata.height || metadata.width > LIMITS.dimension || metadata.height > LIMITS.dimension || metadata.orientation !== undefined && metadata.orientation !== 1) fail("Directing anchors require a single unrotated PNG, JPEG, or WebP image no larger than 4096 pixels per side.");
+  if (!extension || !["png", "jpg", "webp"].includes(extension) || metadata.pages !== undefined && metadata.pages !== 1 || !metadata.width || !metadata.height || metadata.width > LIMITS.dimension || metadata.height > LIMITS.dimension || metadata.orientation !== undefined && metadata.orientation !== 1) fail("Directing anchors require a single unrotated PNG, JPEG, or WebP image no larger than 4096 pixels per side, or self-contained MP4/QuickTime video.");
   await sharp(bytes, { limitInputPixels: LIMITS.dimension ** 2, failOn: "error" }).raw().toBuffer();
   const artifact = await publishBytes(application, bytes, extension, signal);
   return GatewayMediaSourceReferenceSchema.parse({ ...artifact, mediaType: metadata.format === "jpeg" ? "image/jpeg" : `image/${metadata.format}`, facts: { width: metadata.width, height: metadata.height } });

package/apps/desktop/cli/directing-quote.ts

@@ -1,5 +1,5 @@
 import type { DirectingQuote, DirectingShot } from "../application/directing-contract";
-import type { GatewayMediaCatalogView, GatewayJsonValue } from "./gateway-media-catalog";
+import { providerVideoResolution, type GatewayMediaCatalogView, type GatewayJsonValue } from "./gateway-media-catalog";
 import { CliError } from "./errors";
 
 /** Integer microdollars avoid floating point drift across small paid attempts. */
@@ -42,9 +42,13 @@ export function quoteDirectingShot(
   const model = catalog.snapshot.models.find(value => value.id === shot.model);
   if (model?.kind !== "video" || model.executionMode !== "video-model") unsupported("the selected model is not a batch video model.");
   const capability = model.capabilities;
-  const operation = shot.lastFrame !== undefined ? "first-last-frame" : shot.firstFrame !== undefined ? "image-to-video" : "text-to-video";
+  const hasVideoReference = (shot.references ?? []).some(reference => reference.mediaType.startsWith("video/"));
+  const operations = (shot.references?.length ?? 0) > 0
+    ? ["reference-to-video", ...(hasVideoReference ? ["video-editing", "motion-control", "extend-video"] : [])]
+    : [shot.lastFrame !== undefined ? "first-last-frame" : shot.firstFrame !== undefined ? "image-to-video" : "text-to-video"];
+  const supportedOperations = capability?.["supported_operations"];
+  if (!Array.isArray(supportedOperations) || !operations.some(operation => supportedOperations.includes(operation))) unsupported(`the catalog does not confirm any of the shot's operations (${operations.join(", ")}).`);
   for (const [key, value] of [
-    ["supported_operations", operation],
     ["supported_resolutions", shot.resolution],
     ["supported_aspect_ratios", shot.aspectRatio],
     ["supported_durations_seconds", shot.durationSeconds],
@@ -53,6 +57,9 @@ export function quoteDirectingShot(
     const supported = capability?.[key];
     if (!Array.isArray(supported) || !supported.includes(value)) unsupported(`the catalog does not confirm ${key}=${value}.`);
   }
+  if (providerVideoResolution(model.id, shot.resolution, shot.aspectRatio) === null) {
+    unsupported(`the provider cannot express resolution ${shot.resolution} at aspect ${shot.aspectRatio}.`);
+  }
   if (model.pricing.varies_by_provider === true) unsupported("provider-dependent pricing cannot establish a bounded reservation.");
   const rows = model.pricing.video_duration_pricing;
   if (!Array.isArray(rows) || rows.length === 0 || rows.length > 128) unsupported("duration pricing is unavailable.");
@@ -76,14 +83,25 @@ export function quoteDirectingShot(
 
 /** Determine transport from the same catalog used to price the shot. */
 export function directingInputTransport(catalog: GatewayMediaCatalogView, shot: DirectingShot): "none" | "inline" | "url" {
-  if (shot.firstFrame === undefined && shot.lastFrame === undefined) return "none";
+  const kinds = new Set((shot.references ?? []).map(reference => reference.mediaType.split("/")[0]!));
+  if (shot.firstFrame !== undefined || shot.lastFrame !== undefined) kinds.add("image");
+  if (kinds.size === 0) return "none";
   const model = catalog.snapshot.models.find(value => value.id === shot.model);
   const inputLimits = record(model?.capabilities?.input_limits);
-  const images = record(inputLimits?.image);
-  const sources = images?.supported_sources;
-  if (sources === undefined || sources === null) return "inline";
-  if (!Array.isArray(sources) || sources.some(value => typeof value !== "string")) unsupported("invalid image transport capabilities.");
-  if (sources.includes("base64") || sources.includes("buffer")) return "inline";
-  if (sources.includes("url")) return "url";
-  return unsupported("the model has no supported image transport.");
+  let needsUrl = false;
+  for (const kind of kinds) {
+    const sources = record(inputLimits?.[kind])?.supported_sources;
+    if (sources === undefined || sources === null) continue;
+    if (!Array.isArray(sources) || sources.some(value => typeof value !== "string")) unsupported("invalid input transport capabilities.");
+    if (sources.includes("base64") || sources.includes("buffer")) continue;
+    if (sources.includes("url")) { needsUrl = true; continue; }
+    unsupported(`the model has no supported ${kind} input transport.`);
+  }
+  if (needsUrl) {
+    for (const kind of kinds) {
+      const sources = record(inputLimits?.[kind])?.supported_sources;
+      if (Array.isArray(sources) && !sources.includes("url")) unsupported(`the model cannot receive hosted ${kind} references.`);
+    }
+  }
+  return needsUrl ? "url" : "inline";
 }

package/apps/desktop/cli/directing-service.ts

@@ -56,6 +56,8 @@ function snapshot(state: DirectingState) {
     budget: { maximumMicroUsd: state.budgetMicroUsd, reservedMicroUsd, remainingMicroUsd: state.budgetMicroUsd - reservedMicroUsd, notice: BUDGET_NOTICE },
     shots: currentRecipe(state).shots.map(shot => ({
       id: shot.id, prompt: shot.prompt, model: shot.model,
+      conditioning: shot.references === undefined ? shot.firstFrame === undefined ? "none" : "frames" : "references",
+      referenceCount: shot.references?.length ?? 0,
       selectedAttempt: Object.hasOwn(state.selections, shot.id) ? state.selections[shot.id] : null,
       selectionStatus: Object.hasOwn(active, shot.id) ? "accepted" : Object.hasOwn(state.selections, shot.id) ? "stale" : "unselected",
     })),
@@ -189,11 +191,12 @@ async function executeDirectingCommandBody(
       const dependencies = resolveDirectingShot(state, command.shot).dependencies;
       for (const dependency of dependencies) await finishEndpoint(dependency.attemptId);
       const resolved = resolveDirectingShot(state, command.shot), shot = resolved.shot;
-      if ((resolved.firstFrame !== undefined || resolved.lastFrame !== undefined) && !command.allowCloudUpload) throw new CliError("authorization-required", "This take uploads its exact retained image references. Supply --allow-cloud-upload for this request.");
+      const hasLocalInputs = resolved.firstFrame !== undefined || resolved.lastFrame !== undefined || (shot.references?.length ?? 0) > 0;
+      if (hasLocalInputs && !command.allowCloudUpload) throw new CliError("authorization-required", "This take uploads its exact retained media references. Supply --allow-cloud-upload for this request.");
       const catalog = await adapters.catalog.get({ forceRefresh: true, freshness: "require-fresh", signal });
       const quote = quoteDirectingShot(catalog, shot, application.clock.now());
       const needsHosting = directingInputTransport(catalog, shot) === "url";
-      if (needsHosting && (!command.allowReferenceHosting || adapters.createReferenceHosting === undefined)) throw new CliError("authorization-required", "This model requires image URLs. Configure a private Vercel Blob store and supply --allow-reference-hosting for expiring access to these exact reference frames; --allow-cloud-upload is also required.");
+      if (needsHosting && (!command.allowReferenceHosting || adapters.createReferenceHosting === undefined)) throw new CliError("authorization-required", "This model requires media URLs. Configure a private Vercel Blob store and supply --allow-reference-hosting for expiring access to these exact retained references; --allow-cloud-upload is also required.");
       if (quote.costMicroUsd > state.budgetMicroUsd - totalDirectingReservedMicroUsd(state)) throw new CliError("authorization-required", "This take exceeds the remaining directing budget. No paid request was dispatched.");
       const request = await prepareGatewayOperation(application, {
         signal,
@@ -207,6 +210,7 @@ async function executeDirectingCommandBody(
             { frameType: "first_frame" as const, source: resolved.firstFrame },
             ...(resolved.lastFrame === undefined ? [] : [{ frameType: "last_frame" as const, source: resolved.lastFrame }]),
           ] }),
+          ...(resolved.references === undefined ? {} : { references: resolved.references.map(reference => ({ ...reference })) }),
         } },
       });
       const requestId = directingRequestId({ id: state.id, attemptId: command.attempt, recipeSha256: state.activeRecipeSha256, shotSha256: resolved.shotSha256, request });

package/apps/desktop/cli/gateway-media-catalog.ts

@@ -920,3 +920,60 @@ export function createFileGatewayMediaCatalogSnapshotStore(
     },
   };
 }
+
+/**
+ * Alibaba Wan video models advertise normalized catalog resolutions such as
+ * "720p", but the provider API accepts only explicit pixel sizes bound to
+ * the requested aspect ratio ("1280x720"). This adapter translates the
+ * catalog value through Wan's documented size table so local qualification
+ * and duration pricing stay anchored to the catalog row while paid dispatch
+ * sends the provider representation. The `1280x720` (16:9) cell and the
+ * `480x832` enumeration hint are verified against the live provider; the
+ * remaining cells mirror Wan's published size enum.
+ */
+const WAN_RESOLUTION_PIXEL_SIZES: Readonly<
+  Record<string, Readonly<Record<string, string>>>
+> = {
+  "1080p": {
+    "16:9": "1920x1080",
+    "9:16": "1080x1920",
+    "1:1": "1440x1440",
+    "3:4": "1248x1632",
+    "4:3": "1632x1248",
+  },
+  "480p": {
+    "16:9": "832x480",
+    "9:16": "480x832",
+    "1:1": "624x624",
+  },
+  "720p": {
+    "16:9": "1280x720",
+    "9:16": "720x1280",
+    "1:1": "960x960",
+    "3:4": "832x1088",
+    "4:3": "1088x832",
+  },
+};
+
+/**
+ * Resolve the resolution value a provider expects on the wire.
+ * Returns `undefined` when the request carries no resolution, `null` when a
+ * Wan catalog resolution cannot be mapped for the requested aspect ratio,
+ * and the wire-ready value otherwise.
+ */
+export function providerVideoResolution(
+  modelId: string,
+  resolution: string | undefined,
+  aspectRatio: string | undefined,
+): string | null | undefined {
+  if (
+    resolution === undefined
+    || !modelId.startsWith("alibaba/wan-")
+    || !/^[1-9]\d{2,4}p$/iu.test(resolution)
+  ) {
+    return resolution;
+  }
+  // Wan produces 16:9 landscape output when a request omits the aspect ratio.
+  return WAN_RESOLUTION_PIXEL_SIZES[resolution.toLocaleLowerCase("en-US")]
+    ?.[aspectRatio ?? "16:9"] ?? null;
+}

package/apps/desktop/cli/gateway-media-service.ts

@@ -16,6 +16,7 @@ import {
 } from "./gateway-media-artifacts";
 import {
   GATEWAY_MEDIA_CATALOG_URL,
+  providerVideoResolution,
   type GatewayJsonValue,
   type GatewayMediaCatalogView,
   type GatewayMediaKind,
@@ -2930,6 +2931,12 @@ export function createGatewayMediaService(options: Readonly<{
         execution.signal,
       );
       assertVideoCapabilities(catalog.model, request);
+      const wireResolution = providerVideoResolution(
+        catalog.model.id,
+        request.resolution,
+        request.aspectRatio,
+      );
+      if (wireResolution === null) unsupportedModelSetting();
       const dispatchAt = now();
       const credential = await options.loadCredential(dispatchAt);
       const timeout = combineAbortSignals(
@@ -2989,9 +2996,9 @@ export function createGatewayMediaService(options: Readonly<{
             ...(request.providerOptions === undefined
               ? {}
               : { providerOptions: request.providerOptions }),
-            ...(request.resolution === undefined
+            ...(wireResolution === undefined
               ? {}
-              : { resolution: request.resolution }),
+              : { resolution: wireResolution }),
             ...(request.seed === undefined ? {} : { seed: request.seed }),
           });
           return parseGeneratedFiles(sdkResult, "videos", ["video/"]);
@@ -3025,6 +3032,9 @@ export function createGatewayMediaService(options: Readonly<{
             generateAudio: optionalSummaryValue(request.generateAudio),
             maxVideosPerCall: optionalSummaryValue(request.maxVideosPerCall),
             n: optionalSummaryValue(request.n),
+            providerResolution: optionalSummaryValue(
+              wireResolution === request.resolution ? undefined : wireResolution,
+            ),
             resolution: optionalSummaryValue(request.resolution),
             seed: optionalSummaryValue(request.seed),
           }), request.prompt, request.providerOptions),

package/apps/desktop/cli/help.ts

@@ -11,6 +11,8 @@ Commands:
   capabilities                   Discover the exact static capability modules and qualification status
   operations list|show           Discover host-owned typed operations and policies
   diagram init|check|render      Create, validate, or render portable diagram sources
+  diagram sheets init|check|render
+                                 Create and render black-and-white drawing sheets
   scene init|check|inspect|diff|patch|evaluate|audit|render-audit|solve|review|camera-track|generate|plan|render|direction|effects|behavior|temporal-audit
                                  Author and inspect editable directed 3D scene sources
   scene design catalog|init|inspect|set|compile|gallery
@@ -29,6 +31,8 @@ Commands:
   doctor                         Check local render and asset capabilities
   ai models|image|video|speech|transcribe
                                  Discover and run Vercel AI Gateway media models
+  credits status|topup|wait|forget
+                                 Buy and inspect hosted generation credits
   media audio|color              Apply local non-destructive audio and video effects
   menubar [--background]         Run the prebuilt menu-bar companion
   menubar install|uninstall|status  Manage its per-user LaunchAgent
@@ -91,7 +95,7 @@ For local SDK workflows, code run, workflows run and runs resume accept
 The fixed local operation is slopcamera.studio.run; its SDK surface is studio.run().`,
   direct: `Usage:
   slopcamera direct init <recipe.json> [--json]
-  slopcamera direct anchor --input <image> [--json]
+  slopcamera direct anchor --input <media> [--json]
   slopcamera direct plan <recipe.json> [--json]
   slopcamera direct start <recipe.json> --budget-usd <USD> [--json]
   slopcamera direct inspect <direct-id> [--json]
@@ -105,13 +109,13 @@ The fixed local operation is slopcamera.studio.run; its SDK surface is studio.ru
   slopcamera direct assemble <direct-id> [--json]
 
 Init writes a new recipe without overwriting. Edit its ID, shots, prompts and settings.
-Anchor imports one explicit local image and returns a hash-bound source reference.
+Anchor imports one explicit local image or video and returns a hash-bound source reference.
 Plan checks live Gateway video capabilities and duration pricing without a paid call.
 Start retains one budget for the direct ID; starting again cannot reset it.
-Generate dispatches at most one new take and requires a unique take_<id>. Local images,
+Generate dispatches at most one new take and requires a unique take_<id>. Local media,
 including a predecessor's endpoint, require --allow-cloud-upload on that invocation.
 URL-only models require --allow-reference-hosting and a private Vercel Blob store.
-Only exact reference images receive short-lived signed read URLs. Signed URLs and
+Only exact shot references receive short-lived signed read URLs. Signed URLs and
 credentials are not saved. Cleanup deletes those exact objects; inspect cleanup
 receipts and use direct cleanup after interruptions. Blob charges are separate
 from the model catalog estimate and require room in your overall spending limit.
@@ -250,11 +254,19 @@ reconciliation and never automatically overwrites a later revision.`,
   slopcamera diagram check <diagram.json> [--config <file>] [--strict]
   slopcamera diagram render <diagram.json> [--out-dir <directory>]
         [--config <file>] [--scale <number>]
+  slopcamera diagram sheets init <file.drawing.json> [--json]
+  slopcamera diagram sheets check <file.drawing.json> [--json]
+  slopcamera diagram sheets render <file.drawing.json> [--out-dir <directory>] [--json]
 
 These commands delegate to the canonical @hraness/slopcamera parser. Init never overwrites.
 Check parses and lints without writing; --strict exits 2 on findings. Render replaces the same five
 portable derivatives: editable .tldr plus light/dark SVG and PNG. The registered Slopcamera diagram
-operations separately publish equivalent derivatives by content hash for workflow composition.`,
+operations separately publish equivalent derivatives by content hash for workflow composition.
+
+Sheets use a separate .drawing.json format with explicit US Letter or A4 page geometry, black
+line art and outlined uppercase labels. Init never overwrites; check is read-only; render writes
+one vector PDF, one SVG per sheet and a drawing receipt. Geometry checks do not certify legal
+compliance. Drawing sheets are exposed through this CLI and the root SDK, not code/MCP operations.`,
   image: `Usage:
   slopcamera image vectorize <raster-path> --output <file.svg> [--json]
         [--duotone '<#primary,#secondary>'] [--alpha-cutoff <n>] [--timeout-ms <n>]
@@ -368,7 +380,7 @@ run journal.`,
         [--size <width>x<height>] [--aspect-ratio <width>:<height>] [--seed <n>]
         [--max-output-tokens <n>] [--temperature <n>] [--stop <text> ...]
         [--provider-options <json-file>] [--timeout <time>]
-        [--allow-cloud-upload] [--json]
+        [--allow-cloud-upload] [--hosted] [--json]
   slopcamera ai image gallery <subject> --model <id> --output-dir <directory>
         [--kind <image|texture|skybox|backdrop|sprite>] [--count <n>]
         [--vary <axis[=v1,v2][;axis...]>] [--candidates <json-file>]
@@ -396,6 +408,15 @@ Set AI_GATEWAY_API_KEY in the process environment, or run through a linked Verce
 \`vercel env run -- slopcamera …\` so VERCEL_OIDC_TOKEN is injected. Slopcamera never persists,
 prints, or accepts either credential through argv.
 
+Alternatively, prepaid hosted generation bills Hraness Credits instead of your own Gateway
+credential: run \`slopcamera credits topup\` to buy a pack, \`slopcamera credits wait\` to install
+the device token, then \`slopcamera ai image generate --hosted --model <id> --prompt <text>\`.
+Hosted mode admits one prompt-only image per call: --image, --mask, --count, --size,
+--aspect-ratio, --seed, --temperature, --stop, --max-output-tokens, --provider-options and
+--allow-cloud-upload are rejected because the hosted operation currently exposes no input media
+or provider knobs. When no Gateway credential is configured but a credits device token exists,
+ai image generate routes to the hosted service automatically.
+
 The media-model catalog is fetched live from Vercel AI Gateway and cached with a deterministic
 revision. Every image, video, speech, and batch-transcription model of the matching operation is
 executable; streaming-only transcription models remain discoverable and are labeled as such.
@@ -532,6 +553,25 @@ All mutations support --json and return the resulting plan hash.`,
 Options: --kind <kind[,kind]> (repeatable) --from <time> --to <time>
          --around <time> --limit <1..10000> --json | --jsonl`,
   inspect: `Usage: slopcamera inspect <recording> [--fields <csv>] [--json]`,
+  credits: `Usage:
+  slopcamera credits status [--json]
+  slopcamera credits topup [--pack <id>] [--email <address>] [--json]
+  slopcamera credits wait [--timeout <time>] [--json]
+  slopcamera credits forget [--json]
+
+Prepaid credits power hosted Slopcamera generation at api.slopcamera.com — an alternative to
+running your own Vercel AI Gateway credential. \`topup\` opens a hosted checkout page and prints
+its URL; the page renders the current pack list and prices from the live rate card. \`wait\`
+polls the pending claim until payment lands, then stores the returned device token with 0600
+permissions below the CLI state root. \`status\` reads the wallet balance and held amount.
+\`forget\` removes the locally stored token and pending claim; the wallet and its balance are
+unaffected, but a removed token cannot be re-read, so a new top-up issues a fresh token.
+
+Set SLOPCAMERA_CREDITS_TOKEN to supply the device token from the environment instead of local
+state — useful for agents in ephemeral environments. Tokens and claim secrets never appear in
+argv, receipts, or logs. When a configured wallet runs out, paid calls fail with the top-up URL;
+\`credits topup\` on a configured wallet reuses its bound claim so one wallet keeps one identity.`,
+
   media: `Usage:
   slopcamera media audio <media-path> [effects] [--audio-stream <index>]
         [--output <relative-path>] [--json]
@@ -633,7 +673,7 @@ export function commandHelp(topic: readonly string[]): string {
 
 export function completions(words: readonly string[]): readonly string[] {
   const topLevel = [
-    "capabilities", "operations", "diagram", "direct", "studio", "image", "html", "workflows", "code", "runs", "doctor", "ai", "media", "menubar", "support", "outputs", "recordings", "projects", "project", "scene", "inspect", "events", "edit", "analyze", "align", "faces", "fillers", "render", "assets",
+    "capabilities", "operations", "diagram", "direct", "studio", "image", "html", "workflows", "code", "runs", "doctor", "ai", "credits", "media", "menubar", "support", "outputs", "recordings", "projects", "project", "scene", "inspect", "events", "edit", "analyze", "align", "faces", "fillers", "render", "assets",
   ];
   if (words.length <= 1) return topLevel;
   const command = words[0];
@@ -642,7 +682,9 @@ export function completions(words: readonly string[]): readonly string[] {
   if (command === "direct") return ["init", "anchor", "plan", "start", "inspect", "revise", "generate", "resume", "review", "assemble", "cleanup"];
   if (command === "studio") return words[2] === "assets" || words[1] === "assets" ? ["search", "describe", "plan", "import"] : ["init", "bundle", "plan", "probe", "run", "encode", "asset", "assemble", "inspect", "reconcile", "assets"];
   if (command === "operations") return ["list", "show"];
-  if (command === "diagram") return ["check", "render"];
+  if (command === "diagram") return words[1] === "sheets"
+    ? ["init", "check", "render"]
+    : ["init", "check", "render", "sheets"];
   if (command === "image") return ["vectorize", "generate", "gallery", "icon"];
   if (command === "workflows") return ["list", "show", "plan", "run"];
   if (command === "code") return ["init", "check", "plan", "run"];
@@ -664,6 +706,7 @@ export function completions(words: readonly string[]): readonly string[] {
   if (command === "align") return ["analyze", "apply"];
   if (command === "fillers") return ["list", "apply"];
   if (command === "ai") return ["models", "provider-options", "image", "video", "speech", "transcribe"];
+  if (command === "credits") return ["status", "topup", "wait", "forget"];
   if (command === "media") return ["audio", "color"];
   if (command === "render") return ["plan", "run"];
   if (command === "assets") return ["emoji"];

package/apps/desktop/cli/main.ts

@@ -55,7 +55,7 @@ export async function main(
   }
   const paths = await resolveRepositoryPaths(processIo.cwd(), processIo.env);
   if (earlyCommand.kind === "html-render" || earlyCommand.kind === "spatial-world" || earlyCommand.kind === "spatial-asset" || earlyCommand.kind === "spatial-design" || earlyCommand.kind === "directing" || earlyCommand.kind === "studio"
-    || earlyCommand.kind === "spatial-scene" && (earlyCommand.action === "camera-track" || earlyCommand.action === "render-audit" || earlyCommand.action === "review")) {
+    || earlyCommand.kind === "spatial-scene" && (earlyCommand.action === "render" || earlyCommand.action === "camera-track" || earlyCommand.action === "render-audit" || earlyCommand.action === "review")) {
     const controller = new AbortController();
     const cancel = () => controller.abort(new CliError("cancelled", "Command interrupted."));
     process.on("SIGINT", cancel);

package/apps/desktop/cli/project-renderer.ts

@@ -959,6 +959,7 @@ function overlayVideoChain(
   } else {
     filters.push(
       `trim=duration=${seconds(sliceDurationUs)}`,
+      "settb=AVTB",
       `setpts=PTS-STARTPTS+${seconds(resolved.outputRange.startUs)}/TB`,
     );
   }
@@ -1246,7 +1247,7 @@ export async function buildProjectFfmpegInvocation(
     if (overlayInputIndex.has(overlay.overlayId)) continue;
     overlayInputIndex.set(overlay.overlayId, mediaInputIndex.size + overlayInputIndex.size);
     if (overlay.source.kind === "image" || overlay.source.kind === "svg" || overlay.source.kind === "emoji") {
-      inputArguments.push("-loop", "1");
+      inputArguments.push("-loop", "1", "-framerate", emittedRate);
     }
     const prepared = await prepareProjectOverlayMedia(overlay, options);
     preparedOverlayMedia.set(overlay.overlayId, prepared);
@@ -1309,6 +1310,7 @@ export async function buildProjectFfmpegInvocation(
     } else {
       const transparent = `video_blend_canvas_${serial++}`;
       const positioned = `video_blend_positioned_${serial++}`;
+      const layerColorSource = `video_blend_color_source_${serial++}`;
       const layerColor = `video_blend_color_${serial++}`;
       const layerAlphaSource = `video_blend_alpha_source_${serial++}`;
       const layerMask = `video_blend_mask_${serial++}`;
@@ -1317,10 +1319,13 @@ export async function buildProjectFfmpegInvocation(
       const blended = `video_blend_result_${serial++}`;
       filters.push(
         `color=c=black@0:s=${plan.output.pixelWidth}x${plan.output.pixelHeight}:r=${emittedRate}:d=${seconds(plan.output.durationUs)},format=rgba[${transparent}]`,
-        `[${transparent}][${label}]overlay=x=${transform.x}:y=${transform.y}:eof_action=repeat:repeatlast=1:enable='${enable}'[${positioned}]`,
-        `[${positioned}]format=rgba,split=2[${layerColor}][${layerAlphaSource}]`,
+        // Preserve the positioned layer's alpha and blend color channels in RGB.
+        // YUV blend arithmetic changes even uncovered pixels (neutral chroma is 128).
+        `[${transparent}][${label}]overlay=x=${transform.x}:y=${transform.y}:eof_action=repeat:repeatlast=1:enable='${enable}':format=auto[${positioned}]`,
+        `[${positioned}]format=rgba,split=2[${layerColorSource}][${layerAlphaSource}]`,
+        `[${layerColorSource}]format=gbrp[${layerColor}]`,
         `[${layerAlphaSource}]alphaextract[${layerMask}]`,
-        `[${currentVideo}]split=2[${baseBlend}][${baseMerge}]`,
+        `[${currentVideo}]format=gbrp,split=2[${baseBlend}][${baseMerge}]`,
         `[${baseBlend}][${layerColor}]blend=all_mode=${slice.presentation.blendMode}[${blended}]`,
         `[${baseMerge}][${blended}][${layerMask}]maskedmerge[${next}]`,
       );
@@ -1365,15 +1370,23 @@ export async function buildProjectFfmpegInvocation(
     const x = overlayPositionExpression(overlay, "x", bounds.startUs, visibleFullEndUs, animations.entranceUs, animations.exitUs);
     const y = overlayPositionExpression(overlay, "y", bounds.startUs, visibleFullEndUs, animations.entranceUs, animations.exitUs);
     const next = `canvas_${serial++}`;
-    const enable = `between(t,${seconds(resolvedOverlay.outputRange.startUs)},${seconds(chain.visibleEndUs)})`;
+    const staticSource = source.kind === "image" || source.kind === "svg" || source.kind === "emoji";
+    // A still's last decoded PTS can precede the final output frame, especially
+    // after cuts or speed edits. Hold it only inside its half-open interval;
+    // animated sources retain their explicit hide/freeze/loop behavior.
+    const enable = staticSource
+      ? `gte(t,${seconds(resolvedOverlay.outputRange.startUs)})*lt(t,${seconds(chain.visibleEndUs)})`
+      : `between(t,${seconds(resolvedOverlay.outputRange.startUs)},${seconds(chain.visibleEndUs)})`;
+    const terminal = staticSource ? "eof_action=repeat:repeatlast=1" : "eof_action=pass:repeatlast=0";
     const blendMode = overlay.blendMode ?? "normal";
     if (blendMode === "normal") {
       filters.push(
-        `[${currentVideo}][${label}]overlay=x='${x}':y='${y}':eof_action=pass:repeatlast=0:enable='${enable}'[${next}]`,
+        `[${currentVideo}][${label}]overlay=x='${x}':y='${y}':${terminal}:enable='${enable}'[${next}]`,
       );
     } else {
       const transparent = `graphic_blend_canvas_${serial++}`;
       const positioned = `graphic_blend_positioned_${serial++}`;
+      const layerColorSource = `graphic_blend_color_source_${serial++}`;
       const layerColor = `graphic_blend_color_${serial++}`;
       const layerAlphaSource = `graphic_blend_alpha_source_${serial++}`;
       const layerMask = `graphic_blend_mask_${serial++}`;
@@ -1382,10 +1395,11 @@ export async function buildProjectFfmpegInvocation(
       const blended = `graphic_blend_result_${serial++}`;
       filters.push(
         `color=c=black@0:s=${plan.output.pixelWidth}x${plan.output.pixelHeight}:r=${emittedRate}:d=${seconds(plan.output.durationUs)},format=rgba[${transparent}]`,
-        `[${transparent}][${label}]overlay=x='${x}':y='${y}':eof_action=pass:repeatlast=0:enable='${enable}'[${positioned}]`,
-        `[${positioned}]format=rgba,split=2[${layerColor}][${layerAlphaSource}]`,
+        `[${transparent}][${label}]overlay=x='${x}':y='${y}':${terminal}:enable='${enable}':format=auto[${positioned}]`,
+        `[${positioned}]format=rgba,split=2[${layerColorSource}][${layerAlphaSource}]`,
+        `[${layerColorSource}]format=gbrp[${layerColor}]`,
         `[${layerAlphaSource}]alphaextract[${layerMask}]`,
-        `[${currentVideo}]split=2[${baseBlend}][${baseMerge}]`,
+        `[${currentVideo}]format=gbrp,split=2[${baseBlend}][${baseMerge}]`,
         `[${baseBlend}][${layerColor}]blend=all_mode=${blendMode}[${blended}]`,
         `[${baseMerge}][${blended}][${layerMask}]maskedmerge[${next}]`,
       );

package/apps/desktop/cli/spatial-scene-service.ts

@@ -337,7 +337,7 @@ export async function executeSpatialSceneCommand(application: ApplicationContext
   if (command.action === "plan" || command.action === "render") {
     const request = bindSpatialCliExecutionProfile(await readSpatialJson(resolve(application.paths.repositoryRoot, command.request)), command.executionProfile);
     if (command.action === "plan") return planSpatialRender(scene, request);
-    const result = await createApplicationOperationRegistry().execute({ application, abortSignal: new AbortController().signal }, {
+    const result = await createApplicationOperationRegistry().execute({ application, abortSignal: signal ?? new AbortController().signal }, {
       kind: "scene.render", version: 1, input: {
         source: { path: relative(application.paths.repositoryRoot, sourcePath) }, request,
         ...(command.assets === undefined ? {} : { assets: await readSpatialJson(resolve(application.paths.repositoryRoot, command.assets)) }),