@vgai/fal-client-compat 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# @vgai/fal-client-compat
+
+Fal execution modes without a VGAI generation API.
+
+```sh
+npm install --save-dev @fal-ai/client@1.10.1 @vgai/fal-client-compat
+```
+
+The package follows VGAI's source-readable package doctrine and publishes its
+TypeScript `src/` directly. It is author-time tooling; projects that do not
+generate through Fal do not install it.
+
+Game code continues to use the upstream package and upstream endpoint types:
+
+```ts
+import { fal } from '@fal-ai/client';
+
+const result = await fal.subscribe('fal-ai/nano-banana-2', {
+  input: { prompt: 'a brass owl game icon', output_format: 'png', resolution: '1K' },
+});
+```
+
+Reference-conditioned editing uses Fal's native edit endpoint and passes the
+reference images directly:
+
+```ts
+const result = await fal.run('fal-ai/nano-banana-2/edit', {
+  input: {
+    prompt: 'preserve the composition and apply the material reference',
+    image_urls: [compositionDataUrl, materialReferenceUrl],
+    output_format: 'png',
+    resolution: '1K',
+  },
+});
+```
+
+The host selects execution before game setup. Mock mode replaces only standard
+Fetch and performs no network I/O:
+
+```ts
+import { fal } from '@fal-ai/client';
+import { createMockFalFetch } from '@vgai/fal-client-compat/mock';
+
+fal.config({ credentials: 'vgai-mock', fetch: createMockFalFetch() });
+```
+
+Direct/BYOK mode is Fal's normal `credentials` configuration. An optional
+Fetch observer makes its request id automatic provenance without touching the
+credential or authored call:
+
+```ts
+import { createFalClient } from '@fal-ai/client';
+import { createDirectFalFetch } from '@vgai/fal-client-compat/direct';
+
+const fal = createFalClient({
+  credentials: userFalKey,
+  fetch: createDirectFalFetch(),
+});
+```
+
+Managed mode is also configured through Fal's native client options:
+
+```ts
+import { createFalClient } from '@fal-ai/client';
+import { createManagedFalFetch } from '@vgai/fal-client-compat/managed';
+
+const gatewayUrl = 'https://generation.vgai.example';
+const fal = createFalClient({
+  credentials: undefined,
+  proxyUrl: { url: `${gatewayUrl}/fal/proxy`, when: 'always' },
+  fetch: createManagedFalFetch({
+    gatewayUrl,
+    accessToken: () => vgaiSession.accessToken(),
+  }),
+});
+```
+
+The helper does not add a generation API. It only authenticates Fal's normal
+proxy and artifact requests and observes the gateway's audit headers. When
+generated bytes are committed through the project output writer, those facts
+are consumed automatically into the one `.vgai/provenance.json` transaction.
+
+The mock compatibility surface currently implements these native Fal endpoints
+for `fal.run`, `fal.subscribe`, and the corresponding queue calls:
+
+- `fal-ai/nano-banana-2` emits deterministic PNGs containing readable request
+  parameters and a hash-derived visual pattern. `fal-ai/nano-banana-2/edit`
+  does the same while requiring at least one reference image and including the
+  ordered `image_urls` list in artifact identity. The original Nano Banana
+  endpoints remain supported for existing authored calls, but are not VGAI's
+  first-party defaults.
+- `fal-ai/stable-audio` emits deterministic PCM WAV files. The request is
+  embedded as standard WAV metadata and encoded into an audible hash-derived
+  tone pattern, so parameter changes produce visibly and audibly distinct
+  artifacts.
+- `fal-ai/sam-3/3d-objects` emits deterministic 3DGS-style ASCII PLY with
+  position, color, opacity, scale, and rotation properties. Three.js's real
+  `PLYLoader` parses the same bytes used by project output.
+- `fal-ai/minimax/hailuo-02/standard/text-to-video` emits a genuine VP8/WebM
+  motion clip. Request hash selects its visible palette/motion design and the
+  canonical request is retained in an ignorable EBML element; Chromium decode
+  and playback are exercised by the heavy integration proof.
+- `fal-ai/hunyuan_world/image-to-world` returns the endpoint's native
+  `world_file` record. Its bytes mirror the live Hunyuan ZIP: deterministic
+  source/full/sky PNGs plus indexed, vertex-colored `mesh_layer0.ply` and
+  `mesh_layer1.ply`, both parsed by Three.js's real `PLYLoader`. World-to-scene
+  conversion remains an explicit author-time import step; the mock does not
+  pretend Fal returns a VGAI scene document.
+- `fal-ai/hunyuan_world` returns the endpoint's native `image` record as a
+  deterministic 2:1 equirectangular PNG panorama.
+
+Unsupported endpoints and unsupported compatibility subsets fail loudly.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@vgai/fal-client-compat",
+  "author": "Volter AI, Inc.",
+  "license": "Apache-2.0",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Native @fal-ai/client execution across direct, VGAI-managed, and deterministic mock transports.",
+  "homepage": "https://github.com/volter-ai/vgai-engine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/vgai-engine.git",
+    "directory": "packages/fal-client-compat"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    "./direct": "./src/direct.ts",
+    "./mock": "./src/mock.ts",
+    "./managed": "./src/managed.ts"
+  },
+  "dependencies": {
+    "@fal-ai/client": "1.10.1",
+    "fflate": "^0.8.2"
+  },
+  "devDependencies": {
+    "three": "^0.180.0"
+  }
+}

package/src/direct.ts

@@ -0,0 +1,64 @@
+const EXECUTION_RECORDER = Symbol.for('vgai.generative-execution-recorder.v1');
+
+export interface DirectFalFetchOptions {
+  fetch?: typeof globalThis.fetch;
+}
+
+function recordExecution(facts: Record<string, unknown>): void {
+  const recorder = (globalThis as Record<symbol, unknown>)[EXECUTION_RECORDER];
+  if (typeof recorder === 'function') recorder(facts);
+}
+
+function isFalExecution(url: URL): boolean {
+  return (
+    url.protocol === 'https:' && (url.hostname === 'fal.run' || url.hostname === 'queue.fal.run')
+  );
+}
+
+function endpointFrom(url: URL): string | undefined {
+  const path = url.pathname.replace(/^\/+|\/+$/g, '');
+  const requestIndex = path.indexOf('/requests/');
+  const endpoint = requestIndex === -1 ? path : path.slice(0, requestIndex);
+  return endpoint.includes('/') ? endpoint : undefined;
+}
+
+async function responseRequestId(response: Response): Promise<string | undefined> {
+  const header = response.headers.get('x-fal-request-id');
+  if (header) return header;
+  try {
+    const body = (await response.clone().json()) as { request_id?: unknown };
+    return typeof body.request_id === 'string' ? body.request_id : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Observes Fal's ordinary BYOK Fetch traffic without changing or authenticating it. */
+export function createDirectFalFetch(options: DirectFalFetchOptions = {}): typeof fetch {
+  const baseFetch = options.fetch ?? globalThis.fetch;
+  return async (input, init) => {
+    const request = new Request(input, init);
+    const url = new URL(request.url);
+    const response = await baseFetch(request);
+    const model = endpointFrom(url);
+    if (
+      (request.method === 'POST' ||
+        (request.method === 'GET' && url.pathname.includes('/requests/'))) &&
+      isFalExecution(url) &&
+      model &&
+      response.ok
+    ) {
+      const requestId = await responseRequestId(response);
+      const pathRequestId = /\/requests\/([^/]+)/.exec(url.pathname)?.[1];
+      recordExecution({
+        mode: 'direct',
+        provider: 'fal',
+        model,
+        ...(requestId || pathRequestId
+          ? { requestId: requestId ?? decodeURIComponent(pathRequestId!) }
+          : {}),
+      });
+    }
+    return response;
+  };
+}

package/src/managed.ts

@@ -0,0 +1,70 @@
+const EXECUTION_RECORDER = Symbol.for('vgai.generative-execution-recorder.v1');
+
+export interface ManagedFalFetchOptions {
+  gatewayUrl: string;
+  accessToken: string | (() => string | Promise<string>);
+  fetch?: typeof globalThis.fetch;
+}
+
+function recordExecution(facts: Record<string, unknown>): void {
+  const recorder = (globalThis as Record<symbol, unknown>)[EXECUTION_RECORDER];
+  if (typeof recorder === 'function') recorder(facts);
+}
+
+async function accessToken(value: ManagedFalFetchOptions['accessToken']): Promise<string> {
+  return typeof value === 'function' ? value() : value;
+}
+
+/**
+ * Authenticates Fal's normal proxy requests and observes gateway execution
+ * headers. Configure it through the upstream client's standard `fetch` and
+ * `proxyUrl` options; authored Fal calls remain unchanged.
+ */
+export function createManagedFalFetch(options: ManagedFalFetchOptions): typeof fetch {
+  const baseFetch = options.fetch ?? globalThis.fetch;
+  const gateway = new URL(options.gatewayUrl);
+  const falProxy = new URL('/fal/proxy', gateway);
+  const managedFetch: typeof fetch = async (input, init) => {
+    const request = new Request(input, init);
+    const url = new URL(request.url);
+    const managed =
+      url.origin === gateway.origin &&
+      (url.pathname === falProxy.pathname || url.pathname.startsWith('/artifacts/'));
+    if (!managed) return baseFetch(input, init);
+    const headers = new Headers(request.headers);
+    headers.set('Authorization', `Bearer ${await accessToken(options.accessToken)}`);
+    const response = await baseFetch(new Request(request, { headers }));
+    if (response.headers.get('X-VGAI-Generation-Created') === 'true') {
+      recordExecution({
+        mode: 'managed',
+        provider: 'fal',
+        ...(response.headers.get('X-VGAI-Model')
+          ? { model: response.headers.get('X-VGAI-Model')! }
+          : {}),
+        ...(response.headers.get('x-fal-request-id')
+          ? { requestId: response.headers.get('x-fal-request-id')! }
+          : {}),
+        ...(response.headers.get('X-VGAI-Managed-Job-ID')
+          ? { managedJobId: response.headers.get('X-VGAI-Managed-Job-ID')! }
+          : {}),
+      });
+    }
+    const target = request.headers.get('x-fal-target-url');
+    const targetUrl = target ? new URL(target) : null;
+    const requestMatch = targetUrl ? /\/requests\/([^/]+)/.exec(targetUrl.pathname) : null;
+    if (request.method === 'GET' && requestMatch && response.ok) {
+      const model = targetUrl!.pathname.replace(/^\//, '').split('/requests/')[0];
+      recordExecution({
+        mode: 'managed',
+        provider: 'fal',
+        ...(model ? { model } : {}),
+        requestId: decodeURIComponent(requestMatch[1] ?? ''),
+        ...(response.headers.get('X-VGAI-Managed-Job-ID')
+          ? { managedJobId: response.headers.get('X-VGAI-Managed-Job-ID')! }
+          : {}),
+      });
+    }
+    return response;
+  };
+  return managedFetch;
+}

package/src/mock.ts

@@ -0,0 +1,1092 @@
+import { createFalClient, type FalClient } from '@fal-ai/client';
+import type {
+  HunyuanWorldImageToWorldInput,
+  HunyuanWorldImageToWorldOutput,
+  HunyuanWorldInput,
+  HunyuanWorldOutput,
+  MinimaxHailuo02StandardTextToVideoInput,
+  MinimaxHailuo02StandardTextToVideoOutput,
+  NanoBanana2EditInput,
+  NanoBanana2Input,
+  NanoBananaEditInput,
+  NanoBananaInput,
+  NanoBananaOutput,
+  Sam33dObjectsInput,
+  Sam33dObjectsOutput,
+  Seedance2R2VInput,
+  Seedance2VideoOutput,
+  StableAudioInput,
+  StableAudioOutput,
+} from '@fal-ai/client/endpoints';
+import { zipSync } from 'fflate';
+
+const NANO_BANANA_ENDPOINT = 'fal-ai/nano-banana';
+const NANO_BANANA_EDIT_ENDPOINT = 'fal-ai/nano-banana/edit';
+const NANO_BANANA_2_ENDPOINT = 'fal-ai/nano-banana-2';
+const NANO_BANANA_2_EDIT_ENDPOINT = 'fal-ai/nano-banana-2/edit';
+const STABLE_AUDIO_ENDPOINT = 'fal-ai/stable-audio';
+const SAM_3D_OBJECTS_ENDPOINT = 'fal-ai/sam-3/3d-objects';
+const HAILUO_TEXT_TO_VIDEO_ENDPOINT = 'fal-ai/minimax/hailuo-02/standard/text-to-video';
+const SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT = 'bytedance/seedance-2.0/reference-to-video';
+const HUNYUAN_IMAGE_TO_WORLD_ENDPOINT = 'fal-ai/hunyuan_world/image-to-world';
+const HUNYUAN_PANORAMA_ENDPOINT = 'fal-ai/hunyuan_world';
+const SUPPORTED_ENDPOINTS = new Set([
+  NANO_BANANA_ENDPOINT,
+  NANO_BANANA_EDIT_ENDPOINT,
+  NANO_BANANA_2_ENDPOINT,
+  NANO_BANANA_2_EDIT_ENDPOINT,
+  STABLE_AUDIO_ENDPOINT,
+  SAM_3D_OBJECTS_ENDPOINT,
+  HAILUO_TEXT_TO_VIDEO_ENDPOINT,
+  SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT,
+  HUNYUAN_IMAGE_TO_WORLD_ENDPOINT,
+  HUNYUAN_PANORAMA_ENDPOINT,
+]);
+const EXECUTION_RECORDER = Symbol.for('vgai.generative-execution-recorder.v1');
+
+type NanoBananaEndpoint =
+  | typeof NANO_BANANA_ENDPOINT
+  | typeof NANO_BANANA_EDIT_ENDPOINT
+  | typeof NANO_BANANA_2_ENDPOINT
+  | typeof NANO_BANANA_2_EDIT_ENDPOINT;
+type NanoBananaAnyInput =
+  | NanoBananaInput
+  | NanoBananaEditInput
+  | NanoBanana2Input
+  | NanoBanana2EditInput;
+
+type MockTask = {
+  endpoint: string;
+  output:
+    | NanoBananaOutput
+    | StableAudioOutput
+    | Sam33dObjectsOutput
+    | MinimaxHailuo02StandardTextToVideoOutput
+    | Seedance2VideoOutput
+    | HunyuanWorldImageToWorldOutput
+    | HunyuanWorldOutput;
+};
+
+// Four tiny, real VP8/WebM motion designs. Request hash chooses the visible
+// palette/motion; an EBML Void element added below carries canonical input.
+const MOCK_WEBM_TEMPLATES = [
+  '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',
+] as const;
+
+function recordExecution(facts: Record<string, unknown>): void {
+  const recorder = (globalThis as Record<symbol, unknown>)[EXECUTION_RECORDER];
+  if (typeof recorder === 'function') recorder(facts);
+}
+
+export type MockFalClientOptions = {
+  /** Called for observability only; the mock never delegates to the network. */
+  onRequest?: (request: { method: string; url: string }) => void;
+};
+
+const FONT: Readonly<Record<string, readonly string[]>> = {
+  ' ': ['00000', '00000', '00000', '00000', '00000', '00000', '00000'],
+  '-': ['00000', '00000', '00000', '11111', '00000', '00000', '00000'],
+  '.': ['00000', '00000', '00000', '00000', '00000', '01100', '01100'],
+  '/': ['00001', '00010', '00100', '01000', '10000', '00000', '00000'],
+  ':': ['00000', '01100', '01100', '00000', '01100', '01100', '00000'],
+  '?': ['01110', '10001', '00001', '00010', '00100', '00000', '00100'],
+  '0': ['01110', '10001', '10011', '10101', '11001', '10001', '01110'],
+  '1': ['00100', '01100', '00100', '00100', '00100', '00100', '01110'],
+  '2': ['01110', '10001', '00001', '00010', '00100', '01000', '11111'],
+  '3': ['11110', '00001', '00001', '01110', '00001', '00001', '11110'],
+  '4': ['00010', '00110', '01010', '10010', '11111', '00010', '00010'],
+  '5': ['11111', '10000', '10000', '11110', '00001', '00001', '11110'],
+  '6': ['01110', '10000', '10000', '11110', '10001', '10001', '01110'],
+  '7': ['11111', '00001', '00010', '00100', '01000', '01000', '01000'],
+  '8': ['01110', '10001', '10001', '01110', '10001', '10001', '01110'],
+  '9': ['01110', '10001', '10001', '01111', '00001', '00001', '01110'],
+  A: ['01110', '10001', '10001', '11111', '10001', '10001', '10001'],
+  B: ['11110', '10001', '10001', '11110', '10001', '10001', '11110'],
+  C: ['01111', '10000', '10000', '10000', '10000', '10000', '01111'],
+  D: ['11110', '10001', '10001', '10001', '10001', '10001', '11110'],
+  E: ['11111', '10000', '10000', '11110', '10000', '10000', '11111'],
+  F: ['11111', '10000', '10000', '11110', '10000', '10000', '10000'],
+  G: ['01111', '10000', '10000', '10111', '10001', '10001', '01111'],
+  H: ['10001', '10001', '10001', '11111', '10001', '10001', '10001'],
+  I: ['01110', '00100', '00100', '00100', '00100', '00100', '01110'],
+  J: ['00111', '00010', '00010', '00010', '10010', '10010', '01100'],
+  K: ['10001', '10010', '10100', '11000', '10100', '10010', '10001'],
+  L: ['10000', '10000', '10000', '10000', '10000', '10000', '11111'],
+  M: ['10001', '11011', '10101', '10101', '10001', '10001', '10001'],
+  N: ['10001', '11001', '10101', '10011', '10001', '10001', '10001'],
+  O: ['01110', '10001', '10001', '10001', '10001', '10001', '01110'],
+  P: ['11110', '10001', '10001', '11110', '10000', '10000', '10000'],
+  Q: ['01110', '10001', '10001', '10001', '10101', '10010', '01101'],
+  R: ['11110', '10001', '10001', '11110', '10100', '10010', '10001'],
+  S: ['01111', '10000', '10000', '01110', '00001', '00001', '11110'],
+  T: ['11111', '00100', '00100', '00100', '00100', '00100', '00100'],
+  U: ['10001', '10001', '10001', '10001', '10001', '10001', '01110'],
+  V: ['10001', '10001', '10001', '10001', '10001', '01010', '00100'],
+  W: ['10001', '10001', '10001', '10101', '10101', '10101', '01010'],
+  X: ['10001', '10001', '01010', '00100', '01010', '10001', '10001'],
+  Y: ['10001', '10001', '01010', '00100', '00100', '00100', '00100'],
+  Z: ['11111', '00001', '00010', '00100', '01000', '10000', '11111'],
+};
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    return `{${Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function hashBytes(value: string): Uint8Array {
+  // Four independent FNV-1a lanes are expanded with xorshift. This is a
+  // visual identity, not a security primitive, and works identically in a
+  // browser, Node, workers, and tests.
+  const lanes = new Uint32Array([0x811c9dc5, 0x9e3779b9, 0x85ebca6b, 0xc2b2ae35]);
+  const bytes = new TextEncoder().encode(value);
+  for (const byte of bytes) {
+    for (let index = 0; index < lanes.length; index += 1) {
+      const lane = lanes[index];
+      if (lane === undefined) continue;
+      lanes[index] = Math.imul(lane ^ (byte + index * 41), 0x01000193) >>> 0;
+    }
+  }
+  const output = new Uint8Array(32);
+  let state = (lanes[0] ?? 0) ^ (lanes[1] ?? 0) ^ (lanes[2] ?? 0) ^ (lanes[3] ?? 0);
+  for (let index = 0; index < output.length; index += 1) {
+    state ^= state << 13;
+    state ^= state >>> 17;
+    state ^= state << 5;
+    state = (state + (lanes[index % lanes.length] ?? 0) + index * 0x9e3779b9) >>> 0;
+    output[index] = state & 0xff;
+  }
+  return output;
+}
+
+function hex(bytes: Uint8Array): string {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+function concatBytes(parts: readonly Uint8Array[]): Uint8Array {
+  const output = new Uint8Array(parts.reduce((total, part) => total + part.byteLength, 0));
+  let offset = 0;
+  for (const part of parts) {
+    output.set(part, offset);
+    offset += part.byteLength;
+  }
+  return output;
+}
+
+function base64(bytes: Uint8Array): string {
+  const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+  let output = '';
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index] ?? 0;
+    const second = bytes[index + 1] ?? 0;
+    const third = bytes[index + 2] ?? 0;
+    const packed = (first << 16) | (second << 8) | third;
+    output += alphabet[(packed >>> 18) & 63] ?? '';
+    output += alphabet[(packed >>> 12) & 63] ?? '';
+    output += index + 1 < bytes.length ? (alphabet[(packed >>> 6) & 63] ?? '') : '=';
+    output += index + 2 < bytes.length ? (alphabet[packed & 63] ?? '') : '=';
+  }
+  return output;
+}
+
+function imageDimensions(aspectRatio = '1:1'): [number, number] {
+  const [wide, high] = aspectRatio.split(':').map(Number);
+  if (!wide || !high) return [320, 320];
+  if (wide === high) return [320, 320];
+  if (wide > high) return [384, Math.max(192, Math.round((384 * high) / wide))];
+  return [Math.max(192, Math.round((384 * wide) / high)), 384];
+}
+
+function setPixel(
+  pixels: Uint8Array,
+  width: number,
+  height: number,
+  x: number,
+  y: number,
+  color: readonly [number, number, number, number],
+): void {
+  if (x < 0 || y < 0 || x >= width || y >= height) return;
+  const offset = (y * width + x) * 4;
+  pixels.set(color, offset);
+}
+
+function fillRect(
+  pixels: Uint8Array,
+  width: number,
+  height: number,
+  x: number,
+  y: number,
+  rectWidth: number,
+  rectHeight: number,
+  color: readonly [number, number, number, number],
+): void {
+  for (let row = y; row < y + rectHeight; row += 1) {
+    for (let column = x; column < x + rectWidth; column += 1) {
+      setPixel(pixels, width, height, column, row, color);
+    }
+  }
+}
+
+function drawGlyph(
+  pixels: Uint8Array,
+  width: number,
+  height: number,
+  glyph: readonly string[],
+  x: number,
+  y: number,
+  scale: number,
+  color: readonly [number, number, number, number],
+): void {
+  for (let row = 0; row < glyph.length; row += 1) {
+    const line = glyph[row] ?? '';
+    for (let column = 0; column < line.length; column += 1) {
+      if (line[column] === '1') {
+        fillRect(pixels, width, height, x + column * scale, y + row * scale, scale, scale, color);
+      }
+    }
+  }
+}
+
+function drawText(
+  pixels: Uint8Array,
+  width: number,
+  height: number,
+  text: string,
+  x: number,
+  y: number,
+  scale: number,
+  color: readonly [number, number, number, number],
+): void {
+  let cursor = x;
+  for (const rawCharacter of text.toUpperCase()) {
+    drawGlyph(
+      pixels,
+      width,
+      height,
+      FONT[rawCharacter] ?? FONT['?'] ?? [],
+      cursor,
+      y,
+      scale,
+      color,
+    );
+    cursor += 6 * scale;
+    if (cursor + 5 * scale >= width - 12) break;
+  }
+}
+
+function crc32(data: Uint8Array): number {
+  let crc = 0xffffffff;
+  for (const byte of data) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit += 1) {
+      crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function uint32(value: number): Uint8Array {
+  return new Uint8Array([
+    (value >>> 24) & 0xff,
+    (value >>> 16) & 0xff,
+    (value >>> 8) & 0xff,
+    value & 0xff,
+  ]);
+}
+
+function pngChunk(kind: string, data: Uint8Array): Uint8Array {
+  const type = new TextEncoder().encode(kind);
+  return concatBytes([
+    uint32(data.byteLength),
+    type,
+    data,
+    uint32(crc32(concatBytes([type, data]))),
+  ]);
+}
+
+function adler32(data: Uint8Array): number {
+  let first = 1;
+  let second = 0;
+  for (const byte of data) {
+    first = (first + byte) % 65521;
+    second = (second + first) % 65521;
+  }
+  return ((second << 16) | first) >>> 0;
+}
+
+function storeDeflate(data: Uint8Array): Uint8Array {
+  const parts: Uint8Array[] = [new Uint8Array([0x78, 0x01])];
+  for (let offset = 0; offset < data.length; offset += 65535) {
+    const block = data.subarray(offset, Math.min(offset + 65535, data.length));
+    const length = block.byteLength;
+    const inverse = ~length & 0xffff;
+    const final = offset + length >= data.length ? 1 : 0;
+    parts.push(
+      new Uint8Array([
+        final,
+        length & 0xff,
+        (length >>> 8) & 0xff,
+        inverse & 0xff,
+        (inverse >>> 8) & 0xff,
+      ]),
+      block,
+    );
+  }
+  parts.push(uint32(adler32(data)));
+  return concatBytes(parts);
+}
+
+function encodePng(
+  width: number,
+  height: number,
+  pixels: Uint8Array,
+  canonicalInput: string,
+): Uint8Array {
+  const header = new Uint8Array(13);
+  new DataView(header.buffer).setUint32(0, width);
+  new DataView(header.buffer).setUint32(4, height);
+  header[8] = 8;
+  header[9] = 6;
+  const scanlines = new Uint8Array(height * (width * 4 + 1));
+  for (let row = 0; row < height; row += 1) {
+    const target = row * (width * 4 + 1);
+    scanlines[target] = 0;
+    scanlines.set(pixels.subarray(row * width * 4, (row + 1) * width * 4), target + 1);
+  }
+  const metadata = new TextEncoder().encode(
+    `vgai-mock-input\0${base64(new TextEncoder().encode(canonicalInput))}`,
+  );
+  return concatBytes([
+    new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]),
+    pngChunk('IHDR', header),
+    pngChunk('tEXt', metadata),
+    pngChunk('IDAT', storeDeflate(scanlines)),
+    pngChunk('IEND', new Uint8Array()),
+  ]);
+}
+
+function fillBackground(pixels: Uint8Array, width: number, height: number, hash: Uint8Array): void {
+  const primary: [number, number, number, number] = [
+    40 + (hash[0] ?? 0) / 2,
+    40 + (hash[1] ?? 0) / 2,
+    40 + (hash[2] ?? 0) / 2,
+    255,
+  ];
+  const secondary: [number, number, number, number] = [
+    80 + (hash[3] ?? 0) / 3,
+    80 + (hash[4] ?? 0) / 3,
+    80 + (hash[5] ?? 0) / 3,
+    255,
+  ];
+
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const band = Math.floor((x + y + (hash[6] ?? 0)) / (12 + ((hash[7] ?? 0) % 24)));
+      const color = band % 2 === 0 ? primary : secondary;
+      setPixel(pixels, width, height, x, y, color);
+    }
+  }
+}
+
+function drawHashGrid(pixels: Uint8Array, width: number, height: number, hash: Uint8Array): void {
+  const cell = 5;
+  const grid = 17;
+  const gridX = width - grid * cell - 14;
+  const gridY = height - grid * cell - 14;
+  fillRect(
+    pixels,
+    width,
+    height,
+    gridX - 5,
+    gridY - 5,
+    grid * cell + 10,
+    grid * cell + 10,
+    [245, 248, 255, 255],
+  );
+  for (let row = 0; row < grid; row += 1) {
+    for (let column = 0; column < grid; column += 1) {
+      const bitIndex = (row * grid + column) % 256;
+      const filled = ((hash[Math.floor(bitIndex / 8)] ?? 0) >> (bitIndex % 8)) & 1;
+      if (filled) {
+        fillRect(
+          pixels,
+          width,
+          height,
+          gridX + column * cell,
+          gridY + row * cell,
+          cell,
+          cell,
+          [8, 12, 20, 255],
+        );
+      }
+    }
+  }
+}
+
+function mockImage(
+  endpoint: NanoBananaEndpoint,
+  input: NanoBananaAnyInput,
+  index: number,
+): Uint8Array {
+  const canonicalInput = stableJson({ endpoint, input, index });
+  const hash = hashBytes(canonicalInput);
+  const [width, height] = imageDimensions(input.aspect_ratio);
+  const pixels = new Uint8Array(width * height * 4);
+  fillBackground(pixels, width, height, hash);
+  fillRect(pixels, width, height, 10, 10, width - 20, Math.min(118, height - 20), [8, 12, 20, 224]);
+  drawText(pixels, width, height, 'VGAI MOCK', 20, 20, 3, [255, 255, 255, 255]);
+  drawText(
+    pixels,
+    width,
+    height,
+    endpoint.includes('nano-banana-2') ? 'FAL NANO BANANA 2' : 'FAL NANO BANANA',
+    20,
+    48,
+    2,
+    [190, 235, 255, 255],
+  );
+  drawText(pixels, width, height, `PROMPT ${input.prompt}`, 20, 68, 2, [255, 255, 255, 255]);
+  drawText(
+    pixels,
+    width,
+    height,
+    `SEED ${input.seed ?? 'AUTO'} HASH ${hex(hash).slice(0, 10)}`,
+    20,
+    88,
+    2,
+    [255, 230, 150, 255],
+  );
+  drawHashGrid(pixels, width, height, hash);
+  return encodePng(width, height, pixels, canonicalInput);
+}
+
+function createNanoBananaOutput(
+  endpoint: NanoBananaEndpoint,
+  input: NanoBananaAnyInput,
+): NanoBananaOutput {
+  if (!input || typeof input.prompt !== 'string' || input.prompt.trim().length === 0) {
+    throw new Error(`fal mock: ${endpoint} requires a non-empty input.prompt.`);
+  }
+  if (
+    (endpoint === NANO_BANANA_EDIT_ENDPOINT || endpoint === NANO_BANANA_2_EDIT_ENDPOINT) &&
+    (!Array.isArray((input as NanoBananaEditInput | NanoBanana2EditInput).image_urls) ||
+      (input as NanoBananaEditInput | NanoBanana2EditInput).image_urls.length === 0 ||
+      (input as NanoBananaEditInput | NanoBanana2EditInput).image_urls.some(
+        (url) => typeof url !== 'string' || url.trim().length === 0,
+      ))
+  ) {
+    throw new Error(
+      `fal mock: ${endpoint} requires at least one non-empty input.image_urls entry.`,
+    );
+  }
+  if (input.output_format && input.output_format !== 'png') {
+    throw new Error(
+      `fal mock: output_format ${JSON.stringify(input.output_format)} is not implemented; use "png".`,
+    );
+  }
+  const count = Math.min(4, Math.max(1, Math.trunc(input.num_images ?? 1)));
+  const [width, height] = imageDimensions(input.aspect_ratio);
+  return {
+    description: `Deterministic VGAI mock for: ${input.prompt}`,
+    images: Array.from({ length: count }, (_, index) => {
+      const png = mockImage(endpoint, input, index);
+      const digest = hex(hashBytes(base64(png))).slice(0, 16);
+      return {
+        url: `data:image/png;base64,${base64(png)}`,
+        content_type: 'image/png',
+        file_name: `vgai-mock-${digest}.png`,
+        file_size: png.byteLength,
+        width,
+        height,
+      };
+    }),
+  };
+}
+
+function ascii(value: string): Uint8Array {
+  return new TextEncoder().encode(value);
+}
+
+function paddedEven(bytes: Uint8Array): Uint8Array {
+  return bytes.byteLength % 2 === 0 ? bytes : concatBytes([bytes, new Uint8Array(1)]);
+}
+
+function riffChunk(kind: string, data: Uint8Array): Uint8Array {
+  const header = new Uint8Array(8);
+  header.set(ascii(kind), 0);
+  new DataView(header.buffer).setUint32(4, data.byteLength, true);
+  return concatBytes([header, paddedEven(data)]);
+}
+
+function encodeMockWav(input: StableAudioInput): Uint8Array {
+  const canonicalInput = stableJson({ endpoint: STABLE_AUDIO_ENDPOINT, input });
+  const hash = hashBytes(canonicalInput);
+  const requestedSeconds = input.seconds_total ?? 30;
+  const seconds = Math.min(30, Math.max(0.1, requestedSeconds));
+  const sampleRate = 16_000;
+  const sampleCount = Math.ceil(seconds * sampleRate);
+  const samples = new Uint8Array(sampleCount * 2);
+  const view = new DataView(samples.buffer);
+  const segmentSeconds = 0.09 + ((hash[0] ?? 0) / 255) * 0.05;
+
+  for (let index = 0; index < sampleCount; index += 1) {
+    const time = index / sampleRate;
+    const segment = Math.floor(time / segmentSeconds);
+    const segmentPhase = (time % segmentSeconds) / segmentSeconds;
+    const byte = hash[segment % hash.length] ?? 0;
+    const frequency = 180 + byte * 3 + (segment % 5) * 37;
+    const envelope = segmentPhase < 0.08 ? segmentPhase / 0.08 : Math.max(0, 1 - segmentPhase);
+    const gate = segmentPhase < 0.76 ? 1 : 0;
+    const fundamental = Math.sin(2 * Math.PI * frequency * time);
+    const overtone = Math.sin(2 * Math.PI * frequency * 1.5 * time) * 0.28;
+    const sample = Math.max(-1, Math.min(1, (fundamental + overtone) * envelope * gate * 0.32));
+    view.setInt16(index * 2, Math.round(sample * 0x7fff), true);
+  }
+
+  const format = new Uint8Array(16);
+  const formatView = new DataView(format.buffer);
+  formatView.setUint16(0, 1, true);
+  formatView.setUint16(2, 1, true);
+  formatView.setUint32(4, sampleRate, true);
+  formatView.setUint32(8, sampleRate * 2, true);
+  formatView.setUint16(12, 2, true);
+  formatView.setUint16(14, 16, true);
+
+  const comment = paddedEven(concatBytes([ascii(canonicalInput), new Uint8Array(1)]));
+  const infoComment = riffChunk('ICMT', comment);
+  const info = riffChunk('LIST', concatBytes([ascii('INFO'), infoComment]));
+  const chunks = concatBytes([riffChunk('fmt ', format), info, riffChunk('data', samples)]);
+  const header = new Uint8Array(12);
+  header.set(ascii('RIFF'), 0);
+  new DataView(header.buffer).setUint32(4, chunks.byteLength + 4, true);
+  header.set(ascii('WAVE'), 8);
+  return concatBytes([header, chunks]);
+}
+
+function createStableAudioOutput(input: StableAudioInput): StableAudioOutput {
+  if (!input || typeof input.prompt !== 'string' || input.prompt.trim().length === 0) {
+    throw new Error('fal mock: fal-ai/stable-audio requires a non-empty input.prompt.');
+  }
+  if (
+    input.seconds_total !== undefined &&
+    (!Number.isFinite(input.seconds_total) || input.seconds_total <= 0 || input.seconds_total > 30)
+  ) {
+    throw new Error('fal mock: seconds_total must be greater than 0 and no more than 30.');
+  }
+  const wav = encodeMockWav(input);
+  const digest = hex(hashBytes(base64(wav))).slice(0, 16);
+  return {
+    audio_file: {
+      url: `data:audio/wav;base64,${base64(wav)}`,
+      content_type: 'audio/wav',
+      file_name: `vgai-mock-${digest}.wav`,
+      file_size: wav.byteLength,
+    },
+  };
+}
+
+function finiteUnit(value: number): string {
+  return Number.isFinite(value) ? value.toFixed(6) : '0.000000';
+}
+
+function encodeMockGaussianSplatFromCanonical(canonicalInput: string): Uint8Array {
+  const hash = hashBytes(canonicalInput);
+  const count = 256;
+  const rows: string[] = [];
+  for (let index = 0; index < count; index += 1) {
+    const angle = index * 2.3999632297 + ((hash[0] ?? 0) / 255) * Math.PI;
+    const ring = 0.35 + ((hash[index % hash.length] ?? 0) / 255) * 0.8;
+    const layer = (index % 17) / 16 - 0.5;
+    const x = Math.cos(angle) * ring;
+    const y = layer * (1.2 + ((hash[1] ?? 0) / 255) * 0.8);
+    const z = Math.sin(angle) * ring;
+    const red = hash[(index * 3) % hash.length] ?? 0;
+    const green = hash[(index * 3 + 1) % hash.length] ?? 0;
+    const blue = hash[(index * 3 + 2) % hash.length] ?? 0;
+    const scale = -2.6 + ((hash[(index + 7) % hash.length] ?? 0) / 255) * 0.8;
+    rows.push(
+      [
+        finiteUnit(x),
+        finiteUnit(y),
+        finiteUnit(z),
+        red,
+        green,
+        blue,
+        finiteUnit(2.2),
+        finiteUnit(scale),
+        finiteUnit(scale),
+        finiteUnit(scale),
+        finiteUnit(1),
+        finiteUnit(0),
+        finiteUnit(0),
+        finiteUnit(0),
+      ].join(' '),
+    );
+  }
+  const header = [
+    'ply',
+    'format ascii 1.0',
+    `comment vgai_mock_input_base64 ${base64(new TextEncoder().encode(canonicalInput))}`,
+    `element vertex ${count}`,
+    'property float x',
+    'property float y',
+    'property float z',
+    'property uchar red',
+    'property uchar green',
+    'property uchar blue',
+    'property float opacity',
+    'property float scale_0',
+    'property float scale_1',
+    'property float scale_2',
+    'property float rot_0',
+    'property float rot_1',
+    'property float rot_2',
+    'property float rot_3',
+    'end_header',
+  ];
+  return new TextEncoder().encode(`${[...header, ...rows].join('\n')}\n`);
+}
+
+function encodeMockGaussianSplat(input: Sam33dObjectsInput): Uint8Array {
+  return encodeMockGaussianSplatFromCanonical(
+    stableJson({ endpoint: SAM_3D_OBJECTS_ENDPOINT, input }),
+  );
+}
+
+function encodeMockColoredMeshFromCanonical(canonicalInput: string): Uint8Array {
+  const hash = hashBytes(canonicalInput);
+  const columns = 18;
+  const rows = 12;
+  const vertices: string[] = [];
+  const faces: string[] = [];
+  for (let row = 0; row < rows; row += 1) {
+    for (let column = 0; column < columns; column += 1) {
+      const u = column / (columns - 1);
+      const v = row / (rows - 1);
+      const x = (u - 0.5) * 4;
+      const z = (v - 0.5) * 2.5;
+      const wave = Math.sin(u * Math.PI * 3 + (hash[0] ?? 0)) * 0.14;
+      const y = wave + ((hash[(row + column) % hash.length] ?? 0) / 255 - 0.5) * 0.08;
+      const red = 80 + ((hash[(column * 3) % hash.length] ?? 0) % 176);
+      const green = 80 + ((hash[(row * 5 + 1) % hash.length] ?? 0) % 176);
+      const blue = 80 + ((hash[(row + column + 2) % hash.length] ?? 0) % 176);
+      vertices.push([finiteUnit(x), finiteUnit(y), finiteUnit(z), red, green, blue].join(' '));
+    }
+  }
+  for (let row = 0; row < rows - 1; row += 1) {
+    for (let column = 0; column < columns - 1; column += 1) {
+      const topLeft = row * columns + column;
+      const topRight = topLeft + 1;
+      const bottomLeft = topLeft + columns;
+      const bottomRight = bottomLeft + 1;
+      faces.push(`3 ${topLeft} ${bottomLeft} ${topRight}`);
+      faces.push(`3 ${topRight} ${bottomLeft} ${bottomRight}`);
+    }
+  }
+  const header = [
+    'ply',
+    'format ascii 1.0',
+    `comment vgai_mock_input_base64 ${base64(new TextEncoder().encode(canonicalInput))}`,
+    `element vertex ${vertices.length}`,
+    'property float x',
+    'property float y',
+    'property float z',
+    'property uchar red',
+    'property uchar green',
+    'property uchar blue',
+    `element face ${faces.length}`,
+    'property list uchar uint vertex_indices',
+    'end_header',
+  ];
+  return new TextEncoder().encode(`${[...header, ...vertices, ...faces].join('\n')}\n`);
+}
+
+function createSam3dObjectsOutput(input: Sam33dObjectsInput): Sam33dObjectsOutput {
+  if (!input || typeof input.image_url !== 'string' || input.image_url.trim().length === 0) {
+    throw new Error(
+      'fal mock: fal-ai/sam-3/3d-objects requires input.image_url as a non-empty URL or data URI.',
+    );
+  }
+  const ply = encodeMockGaussianSplat(input);
+  const digest = hex(hashBytes(base64(ply))).slice(0, 16);
+  return {
+    gaussian_splat: {
+      url: `data:application/octet-stream;base64,${base64(ply)}`,
+      content_type: 'application/octet-stream',
+      file_name: `vgai-mock-${digest}.ply`,
+      file_size: ply.byteLength,
+    },
+    metadata: [{ object_index: 0 }],
+  };
+}
+
+function decodeBase64(value: string): Uint8Array {
+  const binary = atob(value);
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+
+function ebmlSize(value: number): Uint8Array {
+  for (let width = 1; width <= 4; width += 1) {
+    if (value >= 2 ** (7 * width) - 1) continue;
+    const encoded = new Uint8Array(width);
+    let remaining = value;
+    for (let index = width - 1; index >= 0; index -= 1) {
+      encoded[index] = remaining & 0xff;
+      remaining >>>= 8;
+    }
+    encoded[0] = (encoded[0] ?? 0) | (1 << (8 - width));
+    return encoded;
+  }
+  throw new Error('fal mock: video request metadata is too large.');
+}
+
+function encodeMockWebm(endpoint: string, input: Record<string, unknown>): Uint8Array {
+  const canonicalInput = stableJson({ endpoint, input });
+  const hash = hashBytes(canonicalInput);
+  const template = decodeBase64(MOCK_WEBM_TEMPLATES[(hash[0] ?? 0) % MOCK_WEBM_TEMPLATES.length]!);
+  const metadata = new TextEncoder().encode(`vgai-mock-input\0${canonicalInput}`);
+  // The Segment has unknown length, so a trailing standard EBML Void element
+  // remains inside it and is ignored by decoders while preserving mock input.
+  return concatBytes([template, new Uint8Array([0xec]), ebmlSize(metadata.byteLength), metadata]);
+}
+
+function createHailuoTextToVideoOutput(
+  input: MinimaxHailuo02StandardTextToVideoInput,
+): MinimaxHailuo02StandardTextToVideoOutput {
+  if (!input || typeof input.prompt !== 'string' || input.prompt.trim().length === 0) {
+    throw new Error(
+      'fal mock: fal-ai/minimax/hailuo-02/standard/text-to-video requires a non-empty input.prompt.',
+    );
+  }
+  const video = encodeMockWebm(HAILUO_TEXT_TO_VIDEO_ENDPOINT, input);
+  const digest = hex(hashBytes(base64(video))).slice(0, 16);
+  return {
+    video: {
+      url: `data:video/webm;base64,${base64(video)}`,
+      content_type: 'video/webm',
+      file_name: `vgai-mock-${digest}.webm`,
+      file_size: video.byteLength,
+    },
+  };
+}
+
+function createSeedanceReferenceToVideoOutput(input: Seedance2R2VInput): Seedance2VideoOutput {
+  if (!input || typeof input.prompt !== 'string' || input.prompt.trim().length === 0) {
+    throw new Error(
+      'fal mock: bytedance/seedance-2.0/reference-to-video requires a non-empty input.prompt.',
+    );
+  }
+  if (!Array.isArray(input.video_urls) || input.video_urls.length === 0) {
+    throw new Error(
+      'fal mock: bytedance/seedance-2.0/reference-to-video requires at least one input.video_urls entry.',
+    );
+  }
+  const video = encodeMockWebm(
+    SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT,
+    input as unknown as Record<string, unknown>,
+  );
+  const digest = hex(hashBytes(base64(video))).slice(0, 16);
+  return {
+    seed: input.seed ?? hashBytes(stableJson(input))[0]!,
+    video: {
+      url: `data:video/webm;base64,${base64(video)}`,
+      content_type: 'video/webm',
+      file_name: `vgai-mock-${digest}.webm`,
+      file_size: video.byteLength,
+    },
+  };
+}
+
+function validateWorldInput(input: HunyuanWorldImageToWorldInput): string {
+  if (!input || typeof input.image_url !== 'string' || input.image_url.trim().length === 0) {
+    throw new Error(
+      'fal mock: fal-ai/hunyuan_world/image-to-world requires input.image_url as a non-empty URL or data URI.',
+    );
+  }
+  for (const field of ['classes', 'labels_fg1', 'labels_fg2'] as const) {
+    if (typeof input[field] !== 'string' || input[field].trim().length === 0) {
+      throw new Error(
+        `fal mock: fal-ai/hunyuan_world/image-to-world requires non-empty input.${field}.`,
+      );
+    }
+  }
+  return stableJson({ endpoint: HUNYUAN_IMAGE_TO_WORLD_ENDPOINT, input });
+}
+
+function encodeMockWorldImage(canonicalInput: string, label: string): Uint8Array {
+  const hash = hashBytes(`${canonicalInput}:${label}`);
+  const width = 384;
+  const height = 216;
+  const pixels = new Uint8Array(width * height * 4);
+  fillBackground(pixels, width, height, hash);
+  fillRect(pixels, width, height, 10, 10, width - 20, 82, [8, 12, 20, 224]);
+  drawText(pixels, width, height, 'VGAI MOCK HUNYUAN WORLD', 20, 20, 2, [255, 255, 255, 255]);
+  drawText(pixels, width, height, label, 20, 48, 2, [190, 235, 255, 255]);
+  drawHashGrid(pixels, width, height, hash);
+  return encodePng(width, height, pixels, canonicalInput);
+}
+
+function createMockWorldArchive(input: HunyuanWorldImageToWorldInput): Uint8Array {
+  const canonicalInput = validateWorldInput(input);
+  const image = encodeMockWorldImage(canonicalInput, 'SOURCE IMAGE');
+  const fullImage = encodeMockWorldImage(canonicalInput, 'FULL IMAGE');
+  const fullImageSr = encodeMockWorldImage(canonicalInput, 'FULL IMAGE SR');
+  const skyImage = encodeMockWorldImage(canonicalInput, 'SKY IMAGE');
+  const skyImageSr = encodeMockWorldImage(canonicalInput, 'SKY IMAGE SR');
+  const skyMask = encodeMockWorldImage(canonicalInput, 'SKY MASK');
+  const layer0 = encodeMockColoredMeshFromCanonical(`${canonicalInput}:mesh_layer0`);
+  const layer1 = encodeMockColoredMeshFromCanonical(`${canonicalInput}:mesh_layer1`);
+  return zipSync(
+    {
+      'image.png': image,
+      'full_image_sr.png': fullImageSr,
+      'full_image.png': fullImage,
+      'mesh_layer1.ply': layer1,
+      'mesh_layer0.ply': layer0,
+      'sky_image_sr.png': skyImageSr,
+      'sky_mask.png': skyMask,
+      'sky_image.png': skyImage,
+    },
+    { level: 6, mtime: new Date('1980-01-02T00:00:00.000Z') },
+  );
+}
+
+function createHunyuanImageToWorldOutput(
+  input: HunyuanWorldImageToWorldInput,
+): HunyuanWorldImageToWorldOutput {
+  const world = createMockWorldArchive(input);
+  const digest = hex(hashBytes(base64(world))).slice(0, 16);
+  return {
+    world_file: {
+      url: `data:application/zip;base64,${base64(world)}`,
+      content_type: 'application/zip',
+      file_name: `vgai-mock-${digest}.zip`,
+      file_size: world.byteLength,
+    },
+  };
+}
+
+function createHunyuanPanoramaOutput(input: HunyuanWorldInput): HunyuanWorldOutput {
+  if (!input || typeof input.image_url !== 'string' || input.image_url.trim().length === 0) {
+    throw new Error(
+      'fal mock: fal-ai/hunyuan_world requires input.image_url as a non-empty URL or data URI.',
+    );
+  }
+  if (typeof input.prompt !== 'string' || input.prompt.trim().length === 0) {
+    throw new Error('fal mock: fal-ai/hunyuan_world requires a non-empty input.prompt.');
+  }
+  const canonicalInput = stableJson({ endpoint: HUNYUAN_PANORAMA_ENDPOINT, input });
+  const hash = hashBytes(canonicalInput);
+  const width = 384;
+  const height = 192;
+  const pixels = new Uint8Array(width * height * 4);
+  fillBackground(pixels, width, height, hash);
+  fillRect(pixels, width, height, 10, 10, width - 20, 82, [8, 12, 20, 224]);
+  drawText(pixels, width, height, 'VGAI MOCK HUNYUAN', 20, 20, 2, [255, 255, 255, 255]);
+  drawText(pixels, width, height, 'EQUIRECTANGULAR PANORAMA', 20, 48, 2, [190, 235, 255, 255]);
+  drawHashGrid(pixels, width, height, hash);
+  const png = encodePng(width, height, pixels, canonicalInput);
+  const digest = hex(hashBytes(base64(png))).slice(0, 16);
+  return {
+    image: {
+      url: `data:image/png;base64,${base64(png)}`,
+      content_type: 'image/png',
+      file_name: `vgai-mock-${digest}.png`,
+      file_size: png.byteLength,
+      width,
+      height,
+    },
+  };
+}
+
+function createOutput(
+  endpoint: string,
+  input:
+    | NanoBananaInput
+    | NanoBananaEditInput
+    | NanoBanana2Input
+    | NanoBanana2EditInput
+    | StableAudioInput
+    | Sam33dObjectsInput
+    | MinimaxHailuo02StandardTextToVideoInput
+    | Seedance2R2VInput
+    | HunyuanWorldImageToWorldInput
+    | HunyuanWorldInput,
+):
+  | NanoBananaOutput
+  | StableAudioOutput
+  | Sam33dObjectsOutput
+  | MinimaxHailuo02StandardTextToVideoOutput
+  | Seedance2VideoOutput
+  | HunyuanWorldImageToWorldOutput
+  | HunyuanWorldOutput {
+  if (
+    endpoint === NANO_BANANA_ENDPOINT ||
+    endpoint === NANO_BANANA_EDIT_ENDPOINT ||
+    endpoint === NANO_BANANA_2_ENDPOINT ||
+    endpoint === NANO_BANANA_2_EDIT_ENDPOINT
+  ) {
+    return createNanoBananaOutput(endpoint, input as NanoBananaAnyInput);
+  }
+  if (endpoint === STABLE_AUDIO_ENDPOINT) {
+    return createStableAudioOutput(input as StableAudioInput);
+  }
+  if (endpoint === SAM_3D_OBJECTS_ENDPOINT) {
+    return createSam3dObjectsOutput(input as Sam33dObjectsInput);
+  }
+  if (endpoint === HAILUO_TEXT_TO_VIDEO_ENDPOINT) {
+    return createHailuoTextToVideoOutput(input as MinimaxHailuo02StandardTextToVideoInput);
+  }
+  if (endpoint === SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT) {
+    return createSeedanceReferenceToVideoOutput(input as Seedance2R2VInput);
+  }
+  if (endpoint === HUNYUAN_IMAGE_TO_WORLD_ENDPOINT) {
+    return createHunyuanImageToWorldOutput(input as HunyuanWorldImageToWorldInput);
+  }
+  if (endpoint === HUNYUAN_PANORAMA_ENDPOINT) {
+    return createHunyuanPanoramaOutput(input as HunyuanWorldInput);
+  }
+  throw new Error(`fal mock: endpoint ${JSON.stringify(endpoint)} is not implemented.`);
+}
+
+function jsonResponse(body: unknown, status = 200, requestId?: string): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      'content-type': 'application/json',
+      ...(requestId ? { 'x-fal-request-id': requestId } : {}),
+    },
+  });
+}
+
+function endpointFromPath(pathname: string): string {
+  const requestIndex = pathname.indexOf('/requests/');
+  return pathname.slice(1, requestIndex === -1 ? undefined : requestIndex).replace(/\/$/, '');
+}
+
+function queueBase(endpoint: string, requestId: string): string {
+  return `https://queue.fal.run/${endpoint}/requests/${requestId}`;
+}
+
+function submitTask(
+  tasks: Map<string, MockTask>,
+  url: URL,
+  bodyValue: BodyInit | null | undefined,
+): Response {
+  const endpoint = endpointFromPath(url.pathname);
+  const body = typeof bodyValue === 'string' ? JSON.parse(bodyValue) : {};
+  const output = createOutput(
+    endpoint,
+    body as
+      | NanoBananaInput
+      | NanoBananaEditInput
+      | StableAudioInput
+      | Sam33dObjectsInput
+      | MinimaxHailuo02StandardTextToVideoInput
+      | Seedance2R2VInput
+      | HunyuanWorldImageToWorldInput
+      | HunyuanWorldInput,
+  );
+  const requestId = `mock_${hex(hashBytes(stableJson({ endpoint, body }))).slice(0, 24)}`;
+  tasks.set(requestId, { endpoint, output });
+  recordExecution({ mode: 'mock', provider: 'fal', model: endpoint, requestId });
+  if (url.hostname !== 'queue.fal.run') return jsonResponse(output, 200, requestId);
+  const base = queueBase(endpoint, requestId);
+  return jsonResponse({
+    request_id: requestId,
+    response_url: base,
+    status_url: `${base}/status`,
+    cancel_url: `${base}/cancel`,
+  });
+}
+
+function existingTaskResponse(tasks: Map<string, MockTask>, url: URL, method: string): Response {
+  const match = url.pathname.match(/\/requests\/([^/]+)(?:\/(status|cancel))?$/);
+  const requestId = match?.[1];
+  const action = match?.[2];
+  const task = requestId ? tasks.get(requestId) : undefined;
+  if (!requestId || !task) {
+    return jsonResponse({ message: 'fal mock: request was not found.' }, 404, requestId);
+  }
+  const base = queueBase(task.endpoint, requestId);
+  if (method === 'GET') {
+    recordExecution({ mode: 'mock', provider: 'fal', model: task.endpoint, requestId });
+  }
+  if (method === 'GET' && action === 'status') {
+    return jsonResponse({
+      status: 'COMPLETED',
+      request_id: requestId,
+      response_url: base,
+      status_url: `${base}/status`,
+      cancel_url: `${base}/cancel`,
+      logs: [],
+      metrics: { inference_time: 0 },
+    });
+  }
+  if (method === 'GET' && !action) return jsonResponse(task.output, 200, requestId);
+  if (method === 'PUT' && action === 'cancel') return jsonResponse({ status: 'OK' });
+  return jsonResponse({ message: `fal mock: unsupported ${method} request.` }, 400, requestId);
+}
+
+function routeRequest(
+  tasks: Map<string, MockTask>,
+  url: URL,
+  method: string,
+  body: BodyInit | null | undefined,
+): Response {
+  if (url.pathname.includes('/requests/')) {
+    return existingTaskResponse(tasks, url, method);
+  }
+  const endpoint = endpointFromPath(url.pathname);
+  if (!SUPPORTED_ENDPOINTS.has(endpoint)) {
+    return jsonResponse(
+      { message: `fal mock: endpoint ${JSON.stringify(endpoint)} is not implemented.` },
+      400,
+    );
+  }
+  if (method === 'POST') return submitTask(tasks, url, body);
+  return jsonResponse({ message: `fal mock: unsupported ${method} request.` }, 400);
+}
+
+/**
+ * A standard Fetch implementation suitable for `fal.config({ fetch })` or
+ * `createFalClient({ fetch })`. Keeping the seam at Fetch lets a host select
+ * mock mode without changing the provider call authored by a game.
+ */
+export function createMockFalFetch(options: MockFalClientOptions = {}): typeof fetch {
+  const tasks = new Map<string, MockTask>();
+  const mockFetch: typeof fetch = async (input, init) => {
+    const url = new URL(input instanceof Request ? input.url : input.toString());
+    const method = (
+      init?.method ?? (input instanceof Request ? input.method : 'GET')
+    ).toUpperCase();
+    options.onRequest?.({ method, url: url.toString() });
+    try {
+      return routeRequest(tasks, url, method, init?.body);
+    } catch (error) {
+      return jsonResponse(
+        { message: error instanceof Error ? error.message : 'fal mock: invalid request.' },
+        422,
+      );
+    }
+  };
+
+  return mockFetch;
+}
+
+/** Returns the real Fal client preconfigured with `createMockFalFetch()`. */
+export function createMockFalClient(options: MockFalClientOptions = {}): FalClient {
+  return createFalClient({
+    credentials: 'vgai-mock',
+    fetch: createMockFalFetch(options),
+    retry: { maxRetries: 0 },
+  });
+}