@vgai/fal 0.1.1 → 0.1.3

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/fal",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Optional registered Fal provider boundary for VGAI projects: quote, submit, poll and accept behind guarded pricing and credentials.",
   "homepage": "https://github.com/volter-ai/vgai-engine#readme",
@@ -22,17 +22,19 @@
     "./accept": "./src/accept.ts",
     "./cancel": "./src/cancel.ts",
     "./contracts": "./src/contracts.ts",
+    "./glb-measure": "./src/glb-measure.ts",
     "./package.json": "./package.json",
     "./poll": "./src/poll.ts",
     "./pricing": "./src/pricing.ts",
     "./provider": "./src/provider.ts",
+    "./retexture": "./src/retexture.ts",
     "./submit": "./src/submit.ts",
     "./tool-error": "./src/tool-error.ts"
   },
   "dependencies": {
     "@fal-ai/client": "1.10.1",
-    "@vgai/fal-client-compat": "0.1.0",
-    "@vgai/sdk": "0.5.0",
+    "@vgai/fal-client-compat": "0.1.1",
+    "@vgai/sdk": "^0.5.1",
     "fflate": "^0.8.2",
     "three": "^0.180.0",
     "zod": "^4.3.6"
@@ -41,7 +43,7 @@
     "@types/node": "^25.3.0",
     "@types/react": "^19.2.14",
     "@types/three": "^0.180.0",
-    "@vgai/editor-sdk": "0.5.0",
+    "@vgai/editor-sdk": "^0.5.1",
     "react": "^19.2.4"
   }
 }

package/src/accept.ts

@@ -1,9 +1,14 @@
 import { posix } from 'node:path';
 import type { ToolContext } from '@vgai/sdk/tools';
 import { unzipSync } from 'fflate';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
 import { PLYLoader } from 'three/addons/loaders/PLYLoader.js';
-import type { AcceptInput, FalEndpoint } from './contracts.js';
-import { SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT } from './contracts.js';
+import type { AcceptInput, FalEndpoint, GlbMeasurement } from './contracts.js';
+import {
+  MESHY_V5_RETEXTURE_ENDPOINT,
+  SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT,
+} from './contracts.js';
+import { compareGlb, measureGlb } from './glb-measure.js';
 import { quoteFalPrice } from './pricing.js';
 import { falArtifactFetch, falBilling, falClient } from './provider.js';
 
@@ -16,6 +21,7 @@ interface AcceptedFile {
   filename: string;
   mediaType: string;
   bytes: Uint8Array;
+  geometry?: GlbMeasurement;
 }
 
 function directory(value: string): string {
@@ -102,6 +108,73 @@ function ply(bytes: Uint8Array): void {
   }
 }
 
+let scopedSelfUsers = 0;
+let installedScopedSelf = false;
+
+async function withNodeSelf<T>(run: () => Promise<T>): Promise<T> {
+  const globals = globalThis as typeof globalThis & { self?: typeof globalThis };
+  if (!('self' in globals)) {
+    Object.defineProperty(globals, 'self', {
+      value: globalThis,
+      configurable: true,
+      writable: true,
+    });
+    installedScopedSelf = true;
+  }
+  scopedSelfUsers += 1;
+  try {
+    return await run();
+  } finally {
+    scopedSelfUsers -= 1;
+    if (scopedSelfUsers === 0) {
+      if (installedScopedSelf && globals.self === globalThis) delete globals.self;
+      installedScopedSelf = false;
+    }
+  }
+}
+
+/** Proves the accepted bytes load in the production glTF reader. */
+export async function validateGlb(bytes: Uint8Array): Promise<void> {
+  if (
+    bytes.byteLength < 12 ||
+    new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0, true) !== 0x46546c67
+  ) {
+    throw new Error('Fal model is not a GLB container.');
+  }
+  // GLTFLoader uses the browser-standard `self.URL` while resolving embedded
+  // textures. Node exposes URL/Blob on globalThis but does not define `self`.
+  // Scope the alias to validation and reference-count it so parallel accepts
+  // cannot remove it while another parse is still running.
+  const parsed = await withNodeSelf(() =>
+    new GLTFLoader().parseAsync(Uint8Array.from(bytes).buffer, ''),
+  );
+  if (!parsed.scene) throw new Error('Fal GLB has no scene.');
+  parsed.scene.traverse((object) => {
+    const mesh = object as {
+      geometry?: { dispose(): void };
+      material?: { dispose(): void } | Array<{ dispose(): void }>;
+    };
+    mesh.geometry?.dispose();
+    if (Array.isArray(mesh.material))
+      mesh.material.forEach((material) => {
+        material.dispose();
+      });
+    else mesh.material?.dispose();
+  });
+}
+
+async function retexturedModel(
+  data: Record<string, unknown>,
+  fetcher: typeof fetch,
+): Promise<AcceptedFile> {
+  const bytes = await download(nativeFile(data['model_glb'], 'retextured model'), fetcher);
+  await validateGlb(bytes);
+  const geometry = measureGlb(bytes);
+  // A retexture that comes back with no textures did not do its job.
+  if (geometry.textures === 0) throw new Error('Fal retexture output carries no textures.');
+  return { filename: 'model.glb', mediaType: 'model/gltf-binary', bytes, geometry };
+}
+
 async function acceptedFiles(
   endpoint: FalEndpoint,
   data: Record<string, unknown>,
@@ -139,6 +212,9 @@ async function acceptedFiles(
   ) {
     return [await video(nativeFile(data['video'], 'video'), fetcher)];
   }
+  if (endpoint === MESHY_V5_RETEXTURE_ENDPOINT) {
+    return [await retexturedModel(data, fetcher)];
+  }
   if (endpoint === 'fal-ai/hunyuan_world') {
     const bytes = await download(nativeFile(data['image'], 'panorama'), fetcher);
     png(bytes, true);
@@ -177,14 +253,21 @@ export async function acceptFal(input: AcceptInput, ctx: ToolContext) {
   );
   if (!committed.provenanceOperationId)
     throw new Error('Fal output commit returned no provenance operation ID.');
+  if (committed.files.length !== files.length)
+    throw new Error('Fal output commit returned a different file count than it was given.');
+  const outputGeometry = files.length === 1 ? files[0]?.geometry : undefined;
   return {
     requestId: input.requestId,
-    files: committed.files.map((file) => ({
+    files: committed.files.map((file, index) => ({
       path: file.path,
       bytes: file.bytes,
       ...(file.mediaType ? { mediaType: file.mediaType } : {}),
+      ...(files[index]?.geometry ? { geometry: files[index]!.geometry! } : {}),
     })),
     provenanceOperationId: committed.provenanceOperationId,
+    ...(input.sourceGeometry && outputGeometry
+      ? { comparison: compareGlb(input.sourceGeometry, outputGeometry) }
+      : {}),
     ...(quote && usage?.billableUnits !== undefined
       ? { settledAmount: quote.unitPrice * usage.billableUnits }
       : {}),

package/src/contracts.ts

@@ -6,6 +6,7 @@ export const DEFAULT_FAL_IMAGE_EDIT_ENDPOINT = 'fal-ai/nano-banana-2/edit' as co
 export const NANO_BANANA_2_UNDERLYING_ENDPOINT = 'fal-ai/gemini-3.1-flash-image-preview' as const;
 export const SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT =
   'bytedance/seedance-2.0/reference-to-video' as const;
+export const MESHY_V5_RETEXTURE_ENDPOINT = 'fal-ai/meshy/v5/retexture' as const;
 export const FAL_IMAGE_CONTRIBUTION_DEFAULTS = {
   'generate-image': DEFAULT_FAL_IMAGE_ENDPOINT,
   'edit-image': DEFAULT_FAL_IMAGE_EDIT_ENDPOINT,
@@ -22,6 +23,7 @@ export const FalEndpointSchema = z.enum([
   SEEDANCE_2_REFERENCE_TO_VIDEO_ENDPOINT,
   'fal-ai/hunyuan_world/image-to-world',
   'fal-ai/hunyuan_world',
+  MESHY_V5_RETEXTURE_ENDPOINT,
 ]);
 export const SubmissionSchema = z.object({
   mode: ExecutionModeSchema.default('mock'),
@@ -79,7 +81,29 @@ export const CancelResultSchema = z.object({
   requestId: z.string(),
   status: z.literal('cancelled'),
 });
-export const AcceptInputSchema = SubmissionSchema.extend({ requestId: z.string().min(1) });
+/** Geometry and material facts a texturing round-trip can be compared against. */
+export const GlbMeasurementSchema = z.object({
+  meshes: z.number().int().nonnegative(),
+  primitives: z.number().int().nonnegative(),
+  materials: z.number().int().nonnegative(),
+  textures: z.number().int().nonnegative(),
+  vertexCount: z.number().int().nonnegative(),
+  indexCount: z.number().int().nonnegative(),
+  uvSets: z.array(z.string()),
+});
+export const GlbComparisonSchema = z.object({
+  source: GlbMeasurementSchema,
+  output: GlbMeasurementSchema,
+  vertexCountPreserved: z.boolean(),
+  indexCountPreserved: z.boolean(),
+  uvSetsPreserved: z.boolean(),
+  topologyPreserved: z.boolean(),
+});
+export const AcceptInputSchema = SubmissionSchema.extend({
+  requestId: z.string().min(1),
+  /** Measured input geometry, when the submitting presentation had one on disk. */
+  sourceGeometry: GlbMeasurementSchema.optional(),
+});
 export const AcceptResultSchema = z.object({
   requestId: z.string(),
   files: z.array(
@@ -87,11 +111,40 @@ export const AcceptResultSchema = z.object({
       path: z.string(),
       bytes: z.number().int().nonnegative(),
       mediaType: z.string().optional(),
+      geometry: GlbMeasurementSchema.optional(),
     }),
   ),
   provenanceOperationId: z.string(),
   settledAmount: z.number().nonnegative().optional(),
   settledCredits: z.number().nonnegative().optional(),
+  comparison: GlbComparisonSchema.optional(),
+});
+export const RetextureInputSchema = z
+  .object({
+    mode: ExecutionModeSchema.default('mock'),
+    /** Project-relative path to the GLB being retextured. */
+    input: z.string().min(1),
+    /** Meshy's `text_style_prompt`; the endpoint caps it at 600 characters. */
+    textStylePrompt: z.string().min(1).max(600).optional(),
+    /** Meshy's `image_style_url`; a publicly reachable URL or a data URI. */
+    imageStyleUrl: z.string().min(1).optional(),
+    enableOriginalUv: z.boolean().optional(),
+    enablePbr: z.boolean().optional(),
+    enableSafetyChecker: z.boolean().optional(),
+    outputDirectory: z.string().min(1).default('public/generated/fal/retexture'),
+  })
+  .refine(
+    (value) =>
+      [value.textStylePrompt, value.imageStyleUrl].filter((guidance) => guidance !== undefined)
+        .length === 1,
+    { message: 'Retexture takes exactly one of textStylePrompt or imageStyleUrl.' },
+  );
+export const RetextureResultSchema = SubmitResultSchema.extend({
+  source: z.object({
+    path: z.string(),
+    bytes: z.number().int().positive(),
+    geometry: GlbMeasurementSchema,
+  }),
 });
 export type ExecutionMode = z.infer<typeof ExecutionModeSchema>;
 export type FalEndpoint = z.infer<typeof FalEndpointSchema>;
@@ -100,3 +153,6 @@ export type QuoteInput = z.infer<typeof QuoteInputSchema>;
 export type PollInput = z.infer<typeof PollInputSchema>;
 export type CancelInput = z.infer<typeof CancelInputSchema>;
 export type AcceptInput = z.infer<typeof AcceptInputSchema>;
+export type GlbMeasurement = z.infer<typeof GlbMeasurementSchema>;
+export type GlbComparison = z.infer<typeof GlbComparisonSchema>;
+export type RetextureInput = z.infer<typeof RetextureInputSchema>;

package/src/glb-measure.ts

@@ -0,0 +1,106 @@
+import type { GlbComparison, GlbMeasurement } from './contracts.js';
+
+const GLB_MAGIC = 0x46546c67;
+const JSON_CHUNK = 0x4e4f534a;
+
+interface GltfJson {
+  meshes?: Array<{
+    primitives?: Array<{ attributes?: Record<string, number>; indices?: number }>;
+  }>;
+  accessors?: Array<{ count?: number }>;
+  materials?: unknown[];
+  textures?: unknown[];
+  images?: unknown[];
+}
+
+/**
+ * Reads the GLB container's own glTF JSON chunk.
+ *
+ * Deliberately NOT a second glTF runtime: `validateGlb` already proves the bytes
+ * load in the production reader (three's GLTFLoader), and everything measured
+ * here — accessor counts, primitive semantics, the texture list — is metadata
+ * the container states directly. Headless three cannot answer the texture
+ * question at all: in Node it resolves the parse while logging "Couldn't load
+ * texture" and leaves every material map null, so a texture count taken from
+ * the parsed scene would read 0 for a genuinely textured GLB.
+ *
+ * NEW here, and deliberately not shared. The report SHAPE intentionally matches
+ * what `project.tripo.texture` reports so the two retexture providers' accept
+ * results read side by side, but each provider boundary owns its own
+ * implementation: `@vgai/fal` and `@vgai/tripo` are separate published spend
+ * boundaries with no import edge in either direction, and adding one to share
+ * a hundred lines would couple two vendor contracts to each other.
+ */
+function readGltfJson(bytes: Uint8Array): GltfJson {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (bytes.byteLength < 20 || view.getUint32(0, true) !== GLB_MAGIC) {
+    throw new Error('Fal model is not a GLB container.');
+  }
+  let offset = 12;
+  while (offset + 8 <= bytes.byteLength) {
+    const chunkLength = view.getUint32(offset, true);
+    const chunkType = view.getUint32(offset + 4, true);
+    const start = offset + 8;
+    if (start + chunkLength > bytes.byteLength) {
+      throw new Error('GLB chunk table is truncated.');
+    }
+    if (chunkType === JSON_CHUNK) {
+      return JSON.parse(
+        new TextDecoder().decode(bytes.subarray(start, start + chunkLength)),
+      ) as GltfJson;
+    }
+    offset = start + chunkLength;
+  }
+  throw new Error('GLB container has no glTF JSON chunk.');
+}
+
+/** Geometry and material facts a texturing round-trip can be compared against. */
+export function measureGlb(bytes: Uint8Array): GlbMeasurement {
+  const json = readGltfJson(bytes);
+  const accessorCount = (index: number | undefined): number =>
+    typeof index === 'number' ? (json.accessors?.[index]?.count ?? 0) : 0;
+  const primitives = (json.meshes ?? []).flatMap((mesh) => mesh.primitives ?? []);
+  const uvSets = new Set(
+    primitives
+      .flatMap((primitive) => Object.keys(primitive.attributes ?? {}))
+      .filter((semantic) => /^TEXCOORD_\d+$/.test(semantic)),
+  );
+  return {
+    meshes: json.meshes?.length ?? 0,
+    primitives: primitives.length,
+    materials: json.materials?.length ?? 0,
+    textures: json.textures?.length ?? 0,
+    vertexCount: primitives.reduce(
+      (total, primitive) => total + accessorCount(primitive.attributes?.['POSITION']),
+      0,
+    ),
+    indexCount: primitives.reduce(
+      (total, primitive) => total + accessorCount(primitive.indices),
+      0,
+    ),
+    uvSets: [...uvSets].sort(),
+  };
+}
+
+function sameSets(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+/**
+ * Input-vs-output report for a provider retexture. It records what happened; it
+ * decides nothing. Whether Meshy preserves topology and UVs is an open question
+ * that only a REAL run can answer — mock mode returns provider-shaped substitute
+ * geometry, so a mock comparison measures the mock.
+ */
+export function compareGlb(source: GlbMeasurement, output: GlbMeasurement): GlbComparison {
+  const vertexCountPreserved = source.vertexCount === output.vertexCount;
+  const indexCountPreserved = source.indexCount === output.indexCount;
+  return {
+    source,
+    output,
+    vertexCountPreserved,
+    indexCountPreserved,
+    uvSetsPreserved: sameSets(source.uvSets, output.uvSets),
+    topologyPreserved: vertexCountPreserved && indexCountPreserved,
+  };
+}

package/src/pricing.ts

@@ -72,6 +72,22 @@ function nanoBanana2UnitPrice(
   return baseUnitPrice * resolutionMultiplier + webSearchSurcharge + highThinkingSurcharge;
 }
 
+/** Converts Fal's native pricing row plus the native request into the exact
+ * dollar-bearing quote used by both direct tools and the managed gateway. */
+export function falProviderPrice(
+  endpoint: FalEndpoint,
+  input: Record<string, unknown>,
+  price: { unitPrice: number; unit: string },
+): { unitPrice: number; unit: string; quantity?: number; amount?: number } {
+  const unitPrice = nanoBanana2UnitPrice(endpoint, price.unitPrice, input);
+  const count = quantity(price.unit, input);
+  return {
+    unitPrice,
+    unit: price.unit,
+    ...(count === undefined ? {} : { quantity: count, amount: unitPrice * count }),
+  };
+}
+
 async function managedCreditEstimate(
   options: { endpoint: FalEndpoint; input: Record<string, unknown> },
   price: { unitPrice: number; unit: string; quantity?: number },
@@ -127,23 +143,27 @@ export async function quoteFalPrice(options: {
   if (price['currency'] !== undefined && price['currency'] !== 'USD') {
     throw new Error(`Fal returned unsupported pricing currency ${String(price['currency'])}.`);
   }
-  const unitPrice = nanoBanana2UnitPrice(options.endpoint, price['unit_price'], options.input);
-  const count = quantity(price['unit'], options.input);
+  const providerPrice = falProviderPrice(options.endpoint, options.input, {
+    unitPrice: price['unit_price'],
+    unit: price['unit'],
+  });
   const estimatedCredits =
     options.mode === 'managed'
       ? await managedCreditEstimate(options, {
-          unitPrice,
-          unit: price['unit'],
-          ...(count === undefined ? {} : { quantity: count }),
+          unitPrice: providerPrice.unitPrice,
+          unit: providerPrice.unit,
+          ...(providerPrice.quantity === undefined ? {} : { quantity: providerPrice.quantity }),
         })
       : undefined;
   return {
     mode: options.mode,
     endpoint: options.endpoint,
     currency: 'USD',
-    unitPrice,
-    unit: price['unit'],
-    ...(count === undefined ? {} : { quantity: count, estimatedAmount: unitPrice * count }),
+    unitPrice: providerPrice.unitPrice,
+    unit: providerPrice.unit,
+    ...(providerPrice.quantity === undefined
+      ? {}
+      : { quantity: providerPrice.quantity, estimatedAmount: providerPrice.amount }),
     ...(estimatedCredits === undefined ? {} : { estimatedCredits }),
   };
 }

package/src/retexture.ts

@@ -0,0 +1,88 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { extname, resolve, sep } from 'node:path';
+import type { ToolContext } from '@vgai/sdk/tools';
+import { MESHY_V5_RETEXTURE_ENDPOINT, type RetextureInput } from './contracts.js';
+import { measureGlb } from './glb-measure.js';
+import { submitFal } from './submit.js';
+
+/**
+ * The model travels as a base64 data URI inside the JSON request body, which is
+ * the file-input path this package already speaks on both legs: every mock
+ * artifact comes back as one, and `accept` decodes them. Base64 costs a third
+ * again in transit, so the ceiling is stated here rather than discovered as a
+ * provider-side rejection.
+ */
+const MAX_MODEL_BYTES = 32 * 1024 * 1024;
+
+function base64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64');
+}
+
+/**
+ * Resolves one project-relative GLB to bytes, refusing absolute paths, symlink
+ * escapes, non-GLB extensions, and empty or oversized files.
+ */
+async function projectModel(projectRoot: string, projectPath: string) {
+  if (projectPath.startsWith('/') || projectPath.includes('\0')) {
+    throw new Error(`Fal retexture path must be project-relative: ${JSON.stringify(projectPath)}.`);
+  }
+  const root = await realpath(projectRoot);
+  const candidate = resolve(root, projectPath);
+  const absolute = await realpath(candidate).catch(() => {
+    // A raw ENOENT names a resolved absolute path the caller never wrote.
+    throw new Error(
+      `Fal retexture path was not found in the project: ${JSON.stringify(projectPath)}.`,
+    );
+  });
+  if (!absolute.startsWith(`${root}${sep}`)) {
+    throw new Error(`Fal retexture path escapes the project: ${JSON.stringify(projectPath)}.`);
+  }
+  if (extname(absolute).toLowerCase() !== '.glb') {
+    throw new Error(`Fal retexture accepts GLB: ${JSON.stringify(projectPath)}.`);
+  }
+  const info = await stat(absolute);
+  if (!info.isFile() || info.size <= 0 || info.size > MAX_MODEL_BYTES) {
+    const megabytes = Math.round(MAX_MODEL_BYTES / (1024 * 1024));
+    throw new Error(
+      `Fal retexture model must be a non-empty file no larger than ${megabytes} MB: ${projectPath}.`,
+    );
+  }
+  return { path: projectPath, bytes: new Uint8Array(await readFile(absolute)) };
+}
+
+/**
+ * Translates the reviewed authoring input into Meshy's own retexture body. Only
+ * fields the caller set are sent, so every provider default stays the
+ * provider's.
+ */
+function stated(fields: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+
+/**
+ * Retextures an existing project GLB through Meshy on fal: measure it, carry it
+ * in as a data URI, then submit the native queue request. The measurement rides
+ * into acceptance so the accepted bytes can be compared against what went in.
+ */
+export async function retextureFalModel(input: RetextureInput, ctx: ToolContext) {
+  if (!ctx.projectRoot) throw new Error('Fal retexture requires a project root.');
+  const model = await projectModel(ctx.projectRoot, input.input);
+  const geometry = measureGlb(model.bytes);
+  const submitted = await submitFal({
+    mode: input.mode,
+    endpoint: MESHY_V5_RETEXTURE_ENDPOINT,
+    input: stated({
+      model_url: `data:application/octet-stream;base64,${base64(model.bytes)}`,
+      text_style_prompt: input.textStylePrompt,
+      image_style_url: input.imageStyleUrl,
+      enable_original_uv: input.enableOriginalUv,
+      enable_pbr: input.enablePbr,
+      enable_safety_checker: input.enableSafetyChecker,
+    }),
+    outputDirectory: input.outputDirectory,
+  });
+  return {
+    ...submitted,
+    source: { path: model.path, bytes: model.bytes.byteLength, geometry },
+  };
+}