@fungi.computer/darkroom 0.0.0-stage → 0.0.1

package/dist/model-catalog.js

@@ -0,0 +1,565 @@
+import * as z from "zod";
+/** An explicitly requested image encoding; video is outside this contract. */
+export const mediaRequestedImageFormatSchema = z.enum({
+    /** PNG image encoding. */
+    png: "png",
+    /** JPEG image encoding. */
+    jpeg: "jpeg",
+    /** WebP image encoding. */
+    webp: "webp",
+});
+/**
+ * Agent-facing selection tier: cheap/fast draft work, the balanced default,
+ * premium for art the user will see, and max for the most expensive models.
+ * One value per model; never a price.
+ */
+export const mediaModelTierSchema = z.enum({
+    /** Cheap, fast draft model. */
+    draft: "draft",
+    /** Balanced model selection. */
+    balanced: "balanced",
+    /** Premium model selection. */
+    premium: "premium",
+    /** Most expensive model selection. */
+    max: "max",
+});
+/** Media's provider catalog: Workers AI images plus gateway image and video models. */
+export const mediaModelInputSchema = z
+    .strictObject({
+    /** Provider input transport. */
+    transport: z.enum({
+        /** JSON provider input. */
+        json: "json",
+        /** Multipart provider input. */
+        multipart: "multipart",
+    }),
+    /** Whether this model accepts explicit output dimensions. */
+    dimensions: z.enum({
+        /** Provider chooses its own dimensions. */
+        none: "none",
+        /** Provider accepts the requested dimensions. */
+        own: "own",
+    }),
+    /** Maximum accepted dimension in pixels, or null when unbounded by this model. */
+    maxDimension: z.number().int().positive().nullable(),
+    /** Default output width in pixels. */
+    defaultWidth: z.number().int().positive(),
+    /** Default output height in pixels. */
+    defaultHeight: z.number().int().positive(),
+    /** Model-specific inference step count. */
+    steps: z.enum({
+        /** Provider reads the steps field. */
+        steps: "steps",
+        /** Provider reads the num_steps field. */
+        num_steps: "num_steps",
+        /** Provider uses fixed inference steps. */
+        fixed: "fixed",
+    }),
+    /** Maximum model steps, or null when the model has no step ceiling. */
+    maxSteps: z.number().int().positive().nullable(),
+    /** Default inference step count. */
+    defaultSteps: z.number().int().nonnegative().nullable(),
+    /** Provider multipart reference-field prefix, or null when unsupported. */
+    referenceField: z.string().min(1).max(256).nullable(),
+    /** Maximum references accepted by this model. */
+    maxReferences: z.number().int().nonnegative(),
+})
+    .readonly();
+/** Verified Unified AI video identifiers; no inferred family aliases. */
+export const mediaVideoModelIdSchema = z.enum({
+    /** Seedance 2.0. */
+    seedance: "bytedance/seedance-2.0",
+    /** Seedance 2.0 Fast. */
+    seedanceFast: "bytedance/seedance-2.0-fast",
+    /** Seedance 2.0 Mini. */
+    seedanceMini: "bytedance/seedance-2.0-mini",
+    /** Veo 3.1. */
+    veo: "google/veo-3.1",
+    /** Veo 3.1 Fast. */
+    veoFast: "google/veo-3.1-fast",
+    /** MiniMax H3 Max. */
+    minimaxH3Max: "minimax/h3-max",
+});
+/** Provider resolution selectors, refined against the selected catalog entry. */
+export const mediaVideoResolutionSchema = z.enum({
+    /** 480p. */
+    p480: "480p",
+    /** 720p. */
+    p720: "720p",
+    /** 768p, admitted only by MiniMax H3 Max. */
+    p768: "768p",
+    /** 1080p. */
+    p1080: "1080p",
+    /** 4k, admitted only by Seedance 2.0. */
+    p4k: "4k",
+});
+/** Documented video aspect selectors, refined per model. */
+export const mediaVideoAspectRatioSchema = z.enum({
+    /** Landscape widescreen. */
+    wide: "16:9",
+    /** Landscape standard. */
+    landscape: "4:3",
+    /** Square. */
+    square: "1:1",
+    /** Portrait standard. */
+    portrait: "3:4",
+    /** Portrait widescreen. */
+    tall: "9:16",
+    /** Landscape ultrawide. */
+    ultrawide: "21:9",
+    /** Portrait ultrawide. */
+    ultratall: "9:21",
+});
+/** Explicit reference meaning; frame mode and reference mode are exclusive. */
+export const mediaVideoReferenceRoleSchema = z.enum({
+    /** First frame; required when a last frame is supplied. */
+    first: "first-frame",
+    /** Last frame, supported by Seedance only. */
+    last: "last-frame",
+    /** One image in Seedance reference-image mode. */
+    reference: "reference",
+});
+/** One nominal size used to select provider resolution and aspect. */
+export const mediaVideoFormatSchema = z
+    .strictObject({
+    /** Provider resolution. */
+    resolution: mediaVideoResolutionSchema,
+    /** Requested aspect; Seedance may derive actual aspect from its first image. */
+    aspectRatio: mediaVideoAspectRatioSchema,
+    /** Nominal width; actual MP4 dimensions are not decoded. */
+    width: z.number().int().positive(),
+    /** Nominal height; actual MP4 dimensions are not decoded. */
+    height: z.number().int().positive(),
+})
+    .readonly();
+/** Verified video parameters and provider costs, checked 2026-10-11. */
+export const mediaVideoSchema = z
+    .strictObject({
+    /** Minimum duration, for callers displaying bounds. */
+    minSeconds: z.number().int().positive(),
+    /** Maximum duration; durations still owns membership. */
+    maxSeconds: z.number().int().positive(),
+    /** Default duration. */
+    defaultSeconds: z.number().int().positive(),
+    /** Exact accepted whole-second durations. */
+    durations: z.array(z.number().int().positive()).readonly(),
+    /** Verified provider input grammar. */
+    provider: z.enum({
+        /** Seedance integer duration and data-URI image fields. */
+        seedance: "seedance",
+        /** Veo duration string and base64 image_input. */
+        veo: "veo",
+        /** MiniMax multimodal `content[]` array and uppercase resolution. */
+        minimax: "minimax",
+    }),
+    /** Supported resolution/aspect combinations and their nominal selectors. */
+    formats: z.array(mediaVideoFormatSchema).readonly(),
+    /** Resolution selected when omitted. */
+    defaultResolution: mediaVideoResolutionSchema,
+    /** Aspect selected when omitted. */
+    defaultAspectRatio: mediaVideoAspectRatioSchema,
+    /** Audio default, or null when not documented and left to the provider. */
+    defaultGenerateAudio: z.boolean().nullable(),
+    /** Prompt bound: provider bound for Seedance, retained host bound for Veo. */
+    maxPromptLength: z.number().int().positive(),
+    /** Frame or reference roles this provider accepts. */
+    referenceRoles: z.array(mediaVideoReferenceRoleSchema).readonly(),
+    /** Reference-image mode count; first/last frame mode has its own grammar. */
+    maxReferenceImages: z.number().int().nonnegative(),
+    /** Resolutions supporting reference-image mode. */
+    referenceResolutions: z.array(mediaVideoResolutionSchema).readonly(),
+    /** Non-video-input provider cost; 1 USD = 100,000 milliunits. */
+    prices: z
+        .array(z
+        .strictObject({
+        /** Billed output resolution. */
+        resolution: mediaVideoResolutionSchema,
+        /** Provider milliunits per output second without audio. */
+        silentMilliunitsPerSecond: z.number().int().positive(),
+        /** Provider milliunits per output second with audio. */
+        audioMilliunitsPerSecond: z.number().int().positive(),
+    })
+        .readonly())
+        .readonly(),
+})
+    .readonly();
+/** Public wire grammar for a catalog entry returned by the Media owner. */
+export const mediaModelSchema = z
+    .strictObject({
+    /** Provider model identifier. */
+    id: z.string().min(1).max(256),
+    /** Customer-visible model label. */
+    label: z.string().min(1).max(512),
+    /** Outcome or model-kind discriminant. */
+    kind: z.enum({
+        /** Still-image generation. */
+        image: "image",
+        /** Video generation. */
+        video: "video",
+    }),
+    /** Model selection tier, independent of price. */
+    tier: mediaModelTierSchema,
+    /** Verified provider encodings; an empty list refuses pinned formats. */
+    outputFormats: z.array(mediaRequestedImageFormatSchema).max(3).readonly(),
+    /** Model-native input options and reference limits. */
+    input: mediaModelInputSchema,
+    /**
+     * Image output sizes or nominal video selectors, as `WIDTHxHEIGHT`; null means
+     * any size within the input bounds.
+     */
+    sizes: z
+        .array(z.string().regex(/^\d+x\d+$/u))
+        .readonly()
+        .nullable(),
+    /** Video length constraints, or null for a still-image model. */
+    video: mediaVideoSchema.nullable(),
+})
+    .readonly();
+const freezeModel = (model) => Object.freeze({
+    kind: "image",
+    sizes: null,
+    video: null,
+    outputFormats: Object.freeze([]),
+    ...model,
+    input: Object.freeze(model.input),
+});
+const videoShortEdges = {
+    "480p": 480,
+    "720p": 720,
+    "768p": 768,
+    "1080p": 1080,
+    "4k": 2160,
+};
+const videoAspects = {
+    "16:9": [16, 9],
+    "4:3": [4, 3],
+    "1:1": [1, 1],
+    "3:4": [3, 4],
+    "9:16": [9, 16],
+    "21:9": [21, 9],
+    "9:21": [9, 21],
+};
+function videoModel(id, label, tier, provider, rates) {
+    const seedance = provider === "seedance";
+    const aspects = seedance
+        ? mediaVideoAspectRatioSchema.options
+        : [
+            mediaVideoAspectRatioSchema.enum.wide,
+            mediaVideoAspectRatioSchema.enum.tall,
+            mediaVideoAspectRatioSchema.enum.square,
+        ];
+    // Nominal dimensions select resolution/aspect; upstream does not accept pixels.
+    // Round the long edge to even pixels, retaining the existing 854x480 selector.
+    const formats = Object.freeze(rates.flatMap(([resolution]) => aspects.map((aspectRatio) => {
+        const [w, h] = videoAspects[aspectRatio];
+        const edge = videoShortEdges[resolution];
+        const shorter = Math.min(w, h);
+        return Object.freeze({
+            resolution,
+            aspectRatio,
+            width: Math.ceil((edge * w) / shorter / 2) * 2,
+            height: Math.ceil((edge * h) / shorter / 2) * 2,
+        });
+    })));
+    const durations = Object.freeze(seedance ? [4, 5, 6, 7, 8, 9, 10, 11, 12] : [4, 6, 8]);
+    const video = Object.freeze({
+        minSeconds: 4,
+        maxSeconds: seedance ? 12 : 8,
+        defaultSeconds: seedance ? 5 : 6,
+        durations,
+        provider,
+        formats,
+        defaultResolution: "720p",
+        defaultAspectRatio: "16:9",
+        defaultGenerateAudio: seedance ? null : true,
+        maxPromptLength: seedance ? 2000 : 2048,
+        referenceRoles: Object.freeze(seedance
+            ? mediaVideoReferenceRoleSchema.options
+            : [mediaVideoReferenceRoleSchema.enum.first]),
+        maxReferenceImages: seedance ? 4 : 0,
+        referenceResolutions: Object.freeze(seedance
+            ? rates
+                .map(([resolution]) => resolution)
+                .filter((resolution) => resolution !== "1080p")
+            : []),
+        prices: Object.freeze(rates.map(([resolution, silentMilliunitsPerSecond, audioMilliunitsPerSecond]) => Object.freeze({
+            resolution,
+            silentMilliunitsPerSecond,
+            audioMilliunitsPerSecond,
+        }))),
+    });
+    return freezeModel({
+        id,
+        label,
+        tier,
+        kind: "video",
+        video,
+        sizes: Object.freeze(formats.map(({ width, height }) => `${String(width)}x${String(height)}`)),
+        input: {
+            transport: "json",
+            dimensions: "own",
+            maxDimension: Math.max(...formats.map(({ width, height }) => Math.max(width, height))),
+            defaultWidth: 1280,
+            defaultHeight: 720,
+            steps: "fixed",
+            maxSteps: null,
+            defaultSteps: null,
+            referenceField: seedance ? "image" : "image_input",
+            maxReferences: seedance ? 4 : 1,
+        },
+    });
+}
+// MiniMax H3 Max diverges too far from `videoModel()`'s shared seedance/veo
+// shape to reuse it: its wire resolution literals are uppercase ("480P"),
+// its ratio grammar admits no "9:21" selector, and its request body is a
+// multimodal `content[]` array dispatched by `media-generation.ts`, not a
+// flat prompt/image body. https://developers.cloudflare.com/ai/models/minimax/h3-max/
+function minimaxVideoModel() {
+    const resolutions = [
+        "480p",
+        "768p",
+    ];
+    const aspects = [
+        mediaVideoAspectRatioSchema.enum.wide,
+        mediaVideoAspectRatioSchema.enum.landscape,
+        mediaVideoAspectRatioSchema.enum.square,
+        mediaVideoAspectRatioSchema.enum.portrait,
+        mediaVideoAspectRatioSchema.enum.tall,
+        mediaVideoAspectRatioSchema.enum.ultrawide,
+    ];
+    const formats = Object.freeze(resolutions.flatMap((resolution) => aspects.map((aspectRatio) => {
+        const [w, h] = videoAspects[aspectRatio];
+        const edge = videoShortEdges[resolution];
+        const shorter = Math.min(w, h);
+        return Object.freeze({
+            resolution,
+            aspectRatio,
+            width: Math.ceil((edge * w) / shorter / 2) * 2,
+            height: Math.ceil((edge * h) / shorter / 2) * 2,
+        });
+    })));
+    const defaultResolution = mediaVideoResolutionSchema.enum.p768;
+    const defaultAspectRatio = mediaVideoAspectRatioSchema.enum.wide;
+    const defaultFormat = formats.find((format) => format.resolution === defaultResolution &&
+        format.aspectRatio === defaultAspectRatio);
+    if (defaultFormat === undefined)
+        throw new Error("minimax/h3-max is missing its default format");
+    // Integers 5 through 15 inclusive; the documented bound has no gaps.
+    const durations = Object.freeze(Array.from({ length: 11 }, (_, index) => index + 5));
+    const video = Object.freeze({
+        minSeconds: 5,
+        maxSeconds: 15,
+        defaultSeconds: 5,
+        durations,
+        provider: "minimax",
+        formats,
+        defaultResolution,
+        defaultAspectRatio,
+        // Not merely undocumented: the schema has no audio field at all, so the
+        // dispatcher refuses an explicit generateAudio choice outright.
+        defaultGenerateAudio: null,
+        maxPromptLength: 7000,
+        referenceRoles: Object.freeze(mediaVideoReferenceRoleSchema.options),
+        // The host-wide MAX_REFERENCE_COUNT (4) already governs every call; the
+        // vendor page documents up to nine, which this catalog cannot reach.
+        maxReferenceImages: 4,
+        referenceResolutions: Object.freeze(resolutions),
+        prices: Object.freeze([
+            {
+                resolution: mediaVideoResolutionSchema.enum.p480,
+                // No documented audio surcharge; one rate serves both selectors.
+                silentMilliunitsPerSecond: 5_000,
+                audioMilliunitsPerSecond: 5_000,
+            },
+            {
+                resolution: mediaVideoResolutionSchema.enum.p768,
+                silentMilliunitsPerSecond: 8_000,
+                audioMilliunitsPerSecond: 8_000,
+            },
+        ]),
+    });
+    return freezeModel({
+        id: mediaVideoModelIdSchema.enum.minimaxH3Max,
+        label: "MiniMax H3 Max",
+        tier: "balanced",
+        kind: "video",
+        video,
+        sizes: Object.freeze(formats.map(({ width, height }) => `${String(width)}x${String(height)}`)),
+        input: {
+            transport: "json",
+            dimensions: "own",
+            maxDimension: Math.max(...formats.map(({ width, height }) => Math.max(width, height))),
+            defaultWidth: defaultFormat.width,
+            defaultHeight: defaultFormat.height,
+            steps: "fixed",
+            maxSteps: null,
+            defaultSteps: null,
+            // Inert for this gateway model (media-generation.ts builds its body
+            // directly); recorded for the same documentation parity as Seedance/Veo.
+            referenceField: "image_url",
+            maxReferences: 4,
+        },
+    });
+}
+const models = Object.freeze([
+    freezeModel({
+        id: "@cf/black-forest-labs/flux-1-schnell",
+        outputFormats: Object.freeze(["jpeg"]),
+        tier: "draft",
+        label: "Flux 1 Schnell — cheap/fast sketches",
+        input: {
+            transport: "json",
+            dimensions: "none",
+            maxDimension: null,
+            defaultWidth: 1024,
+            defaultHeight: 768,
+            steps: "steps",
+            maxSteps: 8,
+            defaultSteps: 4,
+            referenceField: null,
+            maxReferences: 0,
+        },
+    }),
+    freezeModel({
+        id: "@cf/black-forest-labs/flux-2-klein-4b",
+        tier: "balanced",
+        label: "Flux 2 Klein 4b — balanced default",
+        input: {
+            transport: "multipart",
+            dimensions: "own",
+            maxDimension: 1920,
+            defaultWidth: 1024,
+            defaultHeight: 768,
+            steps: "fixed",
+            maxSteps: null,
+            defaultSteps: 4,
+            referenceField: "input_image_",
+            maxReferences: 4,
+        },
+    }),
+    freezeModel({
+        id: "@cf/black-forest-labs/flux-2-klein-9b",
+        tier: "premium",
+        label: "Flux 2 Klein 9b — higher quality flux-2",
+        input: {
+            transport: "multipart",
+            dimensions: "own",
+            maxDimension: 1920,
+            defaultWidth: 1024,
+            defaultHeight: 768,
+            steps: "fixed",
+            maxSteps: null,
+            defaultSteps: 4,
+            referenceField: "input_image_",
+            maxReferences: 4,
+        },
+    }),
+    freezeModel({
+        id: "@cf/black-forest-labs/flux-2-dev",
+        tier: "max",
+        label: "Flux 2 Dev — best detailed quality, expensive",
+        input: {
+            transport: "multipart",
+            dimensions: "own",
+            maxDimension: 1920,
+            defaultWidth: 1024,
+            defaultHeight: 768,
+            steps: "steps",
+            maxSteps: null,
+            defaultSteps: 20,
+            referenceField: "input_image_",
+            maxReferences: 4,
+        },
+    }),
+    freezeModel({
+        id: "@cf/leonardo/lucid-origin",
+        tier: "premium",
+        label: "Leonardo Lucid Origin — premium prompt adherence",
+        input: {
+            transport: "json",
+            dimensions: "own",
+            maxDimension: 2500,
+            defaultWidth: 1120,
+            defaultHeight: 1120,
+            steps: "num_steps",
+            maxSteps: 40,
+            defaultSteps: null,
+            referenceField: null,
+            maxReferences: 0,
+        },
+    }),
+    freezeModel({
+        id: "@cf/leonardo/phoenix-1.0",
+        tier: "balanced",
+        label: "Leonardo Phoenix 1.0 — best prompt adherence",
+        input: {
+            transport: "json",
+            dimensions: "own",
+            maxDimension: 2048,
+            defaultWidth: 1024,
+            defaultHeight: 1024,
+            steps: "num_steps",
+            maxSteps: 50,
+            defaultSteps: 25,
+            referenceField: null,
+            maxReferences: 0,
+        },
+    }),
+    // Third-party models run through the AI Gateway (Unified Billing): OpenAI's
+    // image model and ByteDance's video model return a result URL, not bytes.
+    freezeModel({
+        id: "openai/gpt-image-2",
+        outputFormats: Object.freeze(["png", "jpeg", "webp"]),
+        tier: "premium",
+        label: "GPT Image 2 — strong text and layout, premium",
+        sizes: Object.freeze(["1024x1024", "1024x1536", "1536x1024"]),
+        input: {
+            transport: "json",
+            dimensions: "own",
+            maxDimension: 1536,
+            defaultWidth: 1024,
+            defaultHeight: 1024,
+            steps: "fixed",
+            maxSteps: null,
+            defaultSteps: null,
+            referenceField: null,
+            maxReferences: 0,
+        },
+    }),
+    videoModel(mediaVideoModelIdSchema.enum.seedance, "Seedance 2.0", "balanced", "seedance", [
+        ["480p", 7_000, 7_000],
+        ["720p", 15_000, 15_000],
+        ["1080p", 37_000, 37_000],
+        ["4k", 78_000, 78_000],
+    ]),
+    videoModel(mediaVideoModelIdSchema.enum.seedanceFast, "Seedance 2.0 Fast", "draft", "seedance", [
+        ["480p", 6_000, 6_000],
+        ["720p", 12_000, 12_000],
+    ]),
+    videoModel(mediaVideoModelIdSchema.enum.seedanceMini, "Seedance 2.0 Mini", "draft", "seedance", [
+        ["480p", 4_000, 4_000],
+        ["720p", 9_000, 9_000],
+    ]),
+    videoModel(mediaVideoModelIdSchema.enum.veo, "Veo 3.1", "premium", "veo", [
+        ["720p", 20_000, 40_000],
+        ["1080p", 20_000, 40_000],
+    ]),
+    videoModel(mediaVideoModelIdSchema.enum.veoFast, "Veo 3.1 Fast", "balanced", "veo", [
+        ["720p", 8_000, 10_000],
+        ["1080p", 10_000, 12_000],
+    ]),
+    minimaxVideoModel(),
+]);
+/** The immutable image and video model catalog. */
+export const mediaModels = models;
+/** List all image and video models in catalog order. */
+export const listMediaModels = () => mediaModels;
+/** Find a model by provider identifier, returning undefined when it is absent. */
+export const getMediaModel = (id) => mediaModels.find((model) => model.id === id);
+/** Invalid generation settings or unsupported model parameters. */
+export class MediaSettingsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MediaSettingsError";
+    }
+}

package/dist/neurons.d.ts

@@ -0,0 +1,4 @@
+/** Published Workers AI image rate: $0.011 per 1,000 neurons. */
+export declare const USD_PER_1K_NEURONS = 0.011;
+/** Convert a neuron estimate to milliunits, rounding up to avoid underquoting. */
+export declare const neuronsToMilliunits: (neurons: number) => number;

package/dist/neurons.js

@@ -0,0 +1,4 @@
+/** Published Workers AI image rate: $0.011 per 1,000 neurons. */
+export const USD_PER_1K_NEURONS = 0.011;
+/** Convert a neuron estimate to milliunits, rounding up to avoid underquoting. */
+export const neuronsToMilliunits = (neurons) => Math.ceil((neurons * 11) / 10);

package/dist/provenance-bytes.d.ts

@@ -0,0 +1,3 @@
+/** Byte composition only; maintained format owners parse and encode containers. */
+export declare function joinBytes(parts: readonly Uint8Array[]): Uint8Array<ArrayBuffer>;
+export declare function startsWithBytes(bytes: Uint8Array, text: string): boolean;

package/dist/provenance-bytes.js

@@ -0,0 +1,15 @@
+/** Byte composition only; maintained format owners parse and encode containers. */
+export function joinBytes(parts) {
+    const result = new Uint8Array(parts.reduce((size, part) => size + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        result.set(part, offset);
+        offset += part.length;
+    }
+    return result;
+}
+export function startsWithBytes(bytes, text) {
+    const prefix = new TextEncoder().encode(text);
+    return (bytes.length >= prefix.length &&
+        prefix.every((value, index) => bytes[index] === value));
+}

package/dist/provenance-export.d.ts

@@ -0,0 +1,23 @@
+/** The admitted Computer file read and generated output share this launch bound. */
+export declare const maximumPrintDownloadBytes: number;
+/** Why a lossless public image export was refused. */
+export type ProvenanceExportFailure = "too-large" | "signed-image" | "invalid-image" | "unsupported-format";
+/** A refusal to export unsafe, unsupported or oversized image bytes. */
+export declare class ProvenanceExportError extends Error {
+    /** Bounded refusal reason. */
+    readonly reason: ProvenanceExportFailure;
+    /** Stable export refusal name. */
+    readonly name = "ProvenanceExportError";
+    constructor(
+    /** Bounded refusal reason. */
+    reason: ProvenanceExportFailure, options?: ErrorOptions);
+}
+/** Lossless browser export. Never mutates the input or falls back to private bytes. */
+export declare function stripPrivateProvenance(bytes: Uint8Array): Promise<{
+    /** Image bytes with private provenance removed. */
+    bytes: Uint8Array;
+    /** Actual output MIME type. */
+    type: string;
+    /** Filename extension matching the output encoding. */
+    extension: string;
+}>;