@fungi.computer/darkroom 0.0.0-stage → 0.1.0

package/dist/gateway-wire.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+/** A result URL every gateway provider must return as plain HTTPS. */
+export declare const resultUrl: z.ZodLazy<z.ZodURL>;
+/** The Unified AI gateway's normalized answer: a completed state and one
+ * result URL. Seedance and Veo answer this way; MiniMax does not. */
+export declare const gatewayOutputSchema: z.ZodLazy<z.ZodObject<{
+    state: z.ZodOptional<z.ZodLiteral<"Completed">>;
+    result: z.ZodObject<{
+        image: z.ZodOptional<z.ZodLazy<z.ZodURL>>;
+        video: z.ZodOptional<z.ZodLazy<z.ZodURL>>;
+    }, z.core.$loose>;
+}, z.core.$loose>>;
+/** Byte ceilings for fetched results; video stays within Worker memory. */
+export declare const GATEWAY_VIDEO_MAX_BYTES: number;
+/** An MP4 carries an `ftyp` box at byte 4. */
+export declare const isMp4: (bytes: Uint8Array) => boolean;

package/dist/gateway-wire.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+/** A result URL every gateway provider must return as plain HTTPS. */
+export const resultUrl = z.lazy(() => z
+    .url()
+    .refine((value) => value.startsWith("https://"), "result URLs must be HTTPS"));
+/** The Unified AI gateway's normalized answer: a completed state and one
+ * result URL. Seedance and Veo answer this way; MiniMax does not. */
+export const gatewayOutputSchema = z.lazy(() => z.looseObject({
+    state: z.literal("Completed").optional(),
+    result: z.looseObject({
+        image: resultUrl.optional(),
+        video: resultUrl.optional(),
+    }),
+}));
+/** Byte ceilings for fetched results; video stays within Worker memory. */
+export const GATEWAY_VIDEO_MAX_BYTES = 64 * 1024 * 1024;
+/** An MP4 carries an `ftyp` box at byte 4. */
+export const isMp4 = (bytes) => bytes.byteLength > 12 &&
+    bytes[4] === 0x66 &&
+    bytes[5] === 0x74 &&
+    bytes[6] === 0x79 &&
+    bytes[7] === 0x70;

package/dist/index.d.ts

@@ -0,0 +1,361 @@
+import * as z from "zod";
+import { type MediaVideoReferenceRole, type MediaVideoModelId, type MediaVideoResolution, type MediaVideoAspectRatio } from "./model-catalog.js";
+export { mediaFailureStageSchema } from "./execution-error.js";
+export { getMediaModel, listMediaModels, mediaModelInputSchema, mediaModelSchema, mediaRequestedImageFormatSchema, mediaModels, mediaModelTierSchema, MediaSettingsError, mediaVideoModelIdSchema, mediaVideoResolutionSchema, mediaVideoAspectRatioSchema, mediaVideoReferenceRoleSchema, mediaVideoFormatSchema, mediaVideoSchema, } from "./model-catalog.js";
+export type { MediaModel, MediaModelInput, MediaModelTier, MediaVideoModelId, MediaVideoResolution, MediaVideoAspectRatio, MediaVideoReferenceRole, MediaVideoModel, MediaVideoFormat, } from "./model-catalog.js";
+/** A reference file selected by the host, with its destination identity and path. */
+export type MediaReference = Readonly<{
+    /** Host-admitted destination or reference identity. */
+    computerId: string;
+    /** Fixed destination or reference file path. */
+    path: string;
+    /** Video reference role; a single untagged host reference means first frame. */
+    role?: MediaVideoReferenceRole;
+}>;
+/** Supported still-image encodings. */
+export type ImageFormat = "png" | "jpeg" | "gif" | "webp";
+/** MIME type corresponding to a supported image encoding. */
+export type ImageMimeType = `image/${ImageFormat}`;
+/** A saved generation: an image, or an MP4 from a video model. */
+export type MediaOutputFormat = ImageFormat | "mp4";
+/** Decoded reference bytes and the dimensions sent to the provider. */
+export type MediaReferenceBytes = Readonly<{
+    /** Decoded reference image bytes. */
+    bytes: Uint8Array;
+    /** Actual reference image encoding. */
+    format: ImageFormat;
+    /** Reference width in pixels. */
+    width: number;
+    /** Reference height in pixels. */
+    height: number;
+    /** Optional filename sent with multipart input. */
+    filename?: string;
+}>;
+/** Normalized model settings, including bounded host-selected references. */
+export type MediaGenerationSettings = Readonly<{
+    /** Catalog model identifier. */
+    model: string;
+    /** Trimmed generation prompt. */
+    prompt: string;
+    /** Requested image width or nominal video resolution/aspect selector. */
+    width: number;
+    /** Requested image height or nominal video resolution/aspect selector. */
+    height: number;
+    /** Model-specific inference steps. */
+    steps?: number;
+    /** Video models only: output length in whole seconds. */
+    durationSeconds?: number;
+    /** Video resolution selector, normalized from the catalog. */
+    resolution?: MediaVideoResolution;
+    /** Requested video aspect; a first image may override it upstream. */
+    aspectRatio?: MediaVideoAspectRatio;
+    /** Audio selection; omitted for Seedance when its default is undocumented. */
+    generateAudio?: boolean;
+    /** Host-authorized reference files. */
+    references?: readonly MediaReference[];
+}>;
+/**
+ * One Media provider call: validated settings and reference bytes in, output
+ * bytes out. Hosts may bind it to Workers AI or their own transport.
+ */
+export type MediaProvider = (settings: MediaGenerationSettings, references: readonly MediaReferenceBytes[], signal?: AbortSignal, outputFormat?: "png" | "jpeg" | "webp") => Promise<Readonly<{
+    /** Generated output bytes. */
+    bytes: Uint8Array;
+    /** Actual output encoding. */
+    format: string;
+}>>;
+/** A decoded reference image, scaled within MAX_REFERENCE_DIMENSION. */
+export type FittedReferenceImage = Omit<MediaReferenceBytes, "filename">;
+/** Decode one reference image and scale it within Media's dimension bound. */
+export type ReferenceImageFitter = (bytes: Uint8Array) => Promise<FittedReferenceImage>;
+/** The long-edge bounds a viewer may ask for when fitting an image to look at. */
+export declare const MIN_VIEW_DIMENSION = 256;
+/** Maximum long-edge size accepted by an image viewer, in pixels. */
+export declare const MAX_VIEW_DIMENSION = 512;
+/** Decode a viewer long-edge size within the supported pixel bounds. */
+export declare const viewDimensionSchema: z.ZodLazy<z.ZodNumber>;
+/**
+ * Decode one image and re-encode it for a model to look at: scaled within
+ * `maxDimension` on the long edge (bounded by {@link viewDimensionSchema}) as
+ * a lossy JPEG, so a viewer can step the dimension down to meet a byte budget.
+ */
+export type ImageViewFitter = (bytes: Uint8Array, maxDimension: number) => Promise<FittedReferenceImage>;
+/** Maximum reference files in one generation request. */
+export declare const MAX_REFERENCE_COUNT = 4;
+/** Maximum reference width and height sent to inference, in pixels. */
+export declare const MAX_REFERENCE_DIMENSION = 512;
+/** Maximum decoded bytes per reference image. */
+export declare const MAX_REFERENCE_BYTES: number;
+/** Maximum retained still-image output bytes. */
+export declare const MAX_OUTPUT_BYTES: number;
+/** Structural wire grammar for one Media generation request. */
+export declare const mediaGenerationSettingsSchema: z.ZodObject<{
+    model: z.ZodString;
+    prompt: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    steps: z.ZodOptional<z.ZodNumber>;
+    durationSeconds: z.ZodOptional<z.ZodNumber>;
+    resolution: z.ZodOptional<z.ZodEnum<{
+        readonly p480: "480p";
+        readonly p720: "720p";
+        readonly p768: "768p";
+        readonly p1080: "1080p";
+        readonly p4k: "4k";
+    }>>;
+    aspectRatio: z.ZodOptional<z.ZodEnum<{
+        readonly wide: "16:9";
+        readonly landscape: "4:3";
+        readonly square: "1:1";
+        readonly portrait: "3:4";
+        readonly tall: "9:16";
+        readonly ultrawide: "21:9";
+        readonly ultratall: "9:21";
+    }>>;
+    generateAudio: z.ZodOptional<z.ZodBoolean>;
+    references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        computerId: z.ZodString;
+        path: z.ZodString;
+        role: z.ZodOptional<z.ZodEnum<{
+            readonly first: "first-frame";
+            readonly last: "last-frame";
+            readonly reference: "reference";
+        }>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/** Caller settings before model defaults and refinements are applied. */
+export type MediaGenerationSettingsInput = z.input<typeof mediaGenerationSettingsSchema>;
+/** App selections contain paths; the host supplies the admitted Computer. */
+export declare const mediaGenerationSelectionSchema: z.ZodObject<{
+    model: z.ZodString;
+    prompt: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    steps: z.ZodOptional<z.ZodNumber>;
+    durationSeconds: z.ZodOptional<z.ZodNumber>;
+    resolution: z.ZodOptional<z.ZodEnum<{
+        readonly p480: "480p";
+        readonly p720: "720p";
+        readonly p768: "768p";
+        readonly p1080: "1080p";
+        readonly p4k: "4k";
+    }>>;
+    aspectRatio: z.ZodOptional<z.ZodEnum<{
+        readonly wide: "16:9";
+        readonly landscape: "4:3";
+        readonly square: "1:1";
+        readonly portrait: "3:4";
+        readonly tall: "9:16";
+        readonly ultrawide: "21:9";
+        readonly ultratall: "9:21";
+    }>>;
+    generateAudio: z.ZodOptional<z.ZodBoolean>;
+    references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        role: z.ZodOptional<z.ZodEnum<{
+            readonly first: "first-frame";
+            readonly last: "last-frame";
+            readonly reference: "reference";
+        }>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/** Generation settings with reference paths resolved by an admitting host. */
+export type MediaGenerationSelection = z.output<typeof mediaGenerationSelectionSchema>;
+/** Validate caller settings and apply retained model defaults. */
+export declare const validateMediaGenerationSettings: (raw: MediaGenerationSettingsInput) => MediaGenerationSettings;
+/** Validate path-only selections without inventing a Computer identity. */
+export declare const validateMediaGenerationSelection: (raw: z.input<typeof mediaGenerationSelectionSchema>) => Readonly<Omit<MediaGenerationSettings, "references"> & {
+    /** Host-authorized reference images. */
+    references?: readonly Readonly<{
+        /** Fixed destination or reference file path. */
+        path: string;
+        /** Video-only reference role. */
+        role?: MediaVideoReferenceRole;
+    }>[];
+}>;
+/** Path-only video reference; the host supplies authority and reads its bytes. */
+export declare const mediaVideoReferenceSchema: z.ZodLazy<z.ZodObject<{
+    path: z.ZodString;
+    role: z.ZodEnum<{
+        readonly first: "first-frame";
+        readonly last: "last-frame";
+        readonly reference: "reference";
+    }>;
+}, z.core.$strict>>;
+/** One path-only video reference. */
+export type MediaVideoReference = z.output<typeof mediaVideoReferenceSchema>;
+/** Neutral video selection; model-specific combinations are checked by validateMediaVideoSelection. */
+export declare const mediaVideoSelectionSchema: z.ZodLazy<z.ZodObject<{
+    model: z.ZodEnum<{
+        readonly seedance: "bytedance/seedance-2.0";
+        readonly seedanceFast: "bytedance/seedance-2.0-fast";
+        readonly seedanceMini: "bytedance/seedance-2.0-mini";
+        readonly veo: "google/veo-3.1";
+        readonly veoFast: "google/veo-3.1-fast";
+        readonly minimaxH3Max: "minimax/h3-max";
+    }>;
+    prompt: z.ZodString;
+    resolution: z.ZodOptional<z.ZodEnum<{
+        readonly p480: "480p";
+        readonly p720: "720p";
+        readonly p768: "768p";
+        readonly p1080: "1080p";
+        readonly p4k: "4k";
+    }>>;
+    aspectRatio: z.ZodOptional<z.ZodEnum<{
+        readonly wide: "16:9";
+        readonly landscape: "4:3";
+        readonly square: "1:1";
+        readonly portrait: "3:4";
+        readonly tall: "9:16";
+        readonly ultrawide: "21:9";
+        readonly ultratall: "9:21";
+    }>>;
+    durationSeconds: z.ZodOptional<z.ZodNumber>;
+    generateAudio: z.ZodOptional<z.ZodBoolean>;
+    references: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodObject<{
+        path: z.ZodString;
+        role: z.ZodEnum<{
+            readonly first: "first-frame";
+            readonly last: "last-frame";
+            readonly reference: "reference";
+        }>;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>;
+/** Caller video selection before defaults and model-specific refinements. */
+export type MediaVideoSelectionInput = z.input<typeof mediaVideoSelectionSchema>;
+/** Normalized path-only video settings, ready for host-authorized reference hydration. */
+export type MediaVideoSelection = Readonly<{
+    /** Verified catalog video identifier. */
+    model: MediaVideoModelId;
+    /** Trimmed, bounded prompt. */
+    prompt: string;
+    /** Nominal width selecting resolution/aspect, not decoded MP4 dimensions. */
+    width: number;
+    /** Nominal height selecting resolution/aspect, not decoded MP4 dimensions. */
+    height: number;
+    /** Validated provider resolution. */
+    resolution: MediaVideoResolution;
+    /** Validated requested aspect. */
+    aspectRatio: MediaVideoAspectRatio;
+    /** Validated output duration in whole seconds. */
+    durationSeconds: number;
+    /** Explicit audio choice, omitted for Seedance when unset. */
+    generateAudio?: boolean;
+    /** Normalized paths and required frame/reference roles. */
+    references?: readonly Readonly<MediaVideoReference>[];
+}>;
+/** Validate supported model/size/duration/reference combinations before authority or billing admission. */
+export declare function validateMediaVideoSelection(raw: MediaVideoSelectionInput): MediaVideoSelection;
+/** Host-authorized reader for decoded reference images. */
+export type MediaReferenceReader = Readonly<{
+    /** Authorize and read one reference into bounded decoded image bytes. */
+    read: (reference: MediaReference) => Promise<MediaReferenceBytes>;
+}>;
+/** Resolve only provider-accepted references through the caller's reader. */
+export declare const resolveMediaReferences: (settings: MediaGenerationSettings, reader: MediaReferenceReader) => Promise<readonly MediaReferenceBytes[]>;
+/** Provider JSON image input for models without multipart references. */
+export type MediaJsonBody = Readonly<{
+    /** Generation prompt. */
+    prompt: string;
+    /** Optional model-native output width. */
+    width?: number;
+    /** Optional model-native output height. */
+    height?: number;
+    /** Steps for models using the steps field. */
+    steps?: number;
+    /** Steps for models using the num_steps field. */
+    num_steps?: number;
+}>;
+/** A model-specific JSON body or multipart form ready for transport. */
+export type MediaProviderPayload = Readonly<{
+    /** Provider input transport. */
+    transport: "json";
+    /** Model-native JSON input. */
+    body: MediaJsonBody;
+}> | Readonly<{
+    /** Provider input transport. */
+    transport: "multipart";
+    /** Platform-encoded multipart image input. */
+    body: FormData;
+}>;
+/** Build the exact JSON or multipart payload required by a retained model. */
+export declare const buildProviderInput: (settings: MediaGenerationSettings, references?: readonly MediaReferenceBytes[]) => MediaProviderPayload;
+/** One image in a provider envelope, encoded inline or available at a URL. */
+export type MediaProviderImageEntry = Readonly<{
+    /** Inline base64 image data. */
+    base64?: string | undefined;
+    /** Inline encoded image data. */
+    data?: string | undefined;
+    /** HTTP image URL fetched through the host. */
+    url?: string | undefined;
+}>;
+/** Parsed provider representation before conversion to bounded image bytes. */
+export type MediaProviderOutput = Readonly<{
+    /** Outcome or model-kind discriminant. */
+    kind: "bytes";
+    /** Generated output bytes. */
+    bytes: Uint8Array;
+}> | Readonly<{
+    /** Outcome or model-kind discriminant. */
+    kind: "response";
+    /** Provider response or encoded image response. */
+    response: Response;
+}> | Readonly<{
+    /** Outcome or model-kind discriminant. */
+    kind: "encoded";
+    /** Inline provider image representation. */
+    encoded: string;
+}> | Readonly<{
+    /** Outcome or model-kind discriminant. */
+    kind: "entries";
+    /** Provider output image entries. */
+    entries: readonly MediaProviderImageEntry[];
+}>;
+/** Decode the Workers AI binding's raw output at the provider boundary. */
+export declare const mediaProviderWireSchema: z.ZodLazy<z.ZodUnion<readonly [z.ZodLazy<z.ZodUnion<readonly [z.ZodObject<{
+    image: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    image: z.ZodArray<z.ZodLazy<z.ZodObject<{
+        base64: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strict>>>;
+}, z.core.$strip>, z.ZodObject<{
+    images: z.ZodArray<z.ZodLazy<z.ZodObject<{
+        base64: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strict>>>;
+}, z.core.$strip>]>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Response, Response>, z.ZodCustom<ReadableStream<Uint8Array<ArrayBufferLike>>, ReadableStream<Uint8Array<ArrayBufferLike>>>]>>;
+/** Supported raw provider representations, decoded by mediaProviderWireSchema. */
+export type MediaProviderWire = z.output<typeof mediaProviderWireSchema>;
+/** Native Workers AI output or an already decoded provider representation. */
+export type MediaAiResult = Awaited<ReturnType<Ai["run"]>> | MediaProviderWire;
+/** Parse the provider wire envelope before normalization. */
+export declare const parseMediaProviderOutput: (value: MediaProviderWire) => MediaProviderOutput;
+/** Read a successful provider response within an explicit byte bound, closing its reader. */
+export declare const readResponseBytes: (response: Response, maximumBytes: number) => Promise<Uint8Array>;
+/** Host-supplied URL fetching and maximum output bytes for normalization. */
+export type MediaProviderOutputOptions = Readonly<{
+    /** Fetch a provider image URL through host-owned transport. */
+    fetchUrl?: (url: string) => Promise<Response>;
+    /** Maximum output bytes, defaulting to MAX_OUTPUT_BYTES. */
+    maxBytes?: number;
+}>;
+/** Normalized bytes and their supported still-image encoding. */
+export type MediaImageOutput = Readonly<{
+    /** Bounded decoded provider bytes. */
+    bytes: Uint8Array;
+    /** Detected or explicitly declared image encoding. */
+    format: ImageFormat;
+}>;
+/** Normalize all retained provider envelopes into bounded image bytes. */
+export declare const normalizeMediaProviderOutput: (value: MediaProviderWire, options?: MediaProviderOutputOptions) => Promise<MediaImageOutput>;
+export { estimateImageMilliunits, estimateImageNeurons, } from "./cost-estimate.js";
+export { neuronsToMilliunits, USD_PER_1K_NEURONS } from "./neurons.js";
+export type { ImageParams, ImageReference } from "./cost-estimate.js";
+/** Authority-free video quote settings; hydrated host settings are structurally compatible. */
+export type MediaVideoQuoteSettings = ReturnType<typeof validateMediaGenerationSelection>;
+/** Provider video cost from the sole catalog, in milliunits (1 cent = 1,000). Video-input references are unsupported. */
+export declare function estimateVideoMilliunits(settings: MediaVideoQuoteSettings): number;