@fungi.computer/darkroom 0.3.0 → 0.4.0

package/docs/api/index.md

@@ -237,23 +237,24 @@ out. Hosts may bind it to Workers AI or their own transport.
 type FittedReferenceImage = Omit<MediaReferenceBytes, "filename">;
 ```
 
-A decoded reference image, scaled within MAX_REFERENCE_DIMENSION.
+A decoded reference image, fitted for the selected model.
 
 ---
 
 ### ReferenceImageFitter
 
 ```ts
-type ReferenceImageFitter = (bytes) => Promise<FittedReferenceImage>;
+type ReferenceImageFitter = (bytes, model) => Promise<FittedReferenceImage>;
 ```
 
-Decode one reference image and scale it within Media's dimension bound.
+Decode and fit a reference: image long edge ≤512, video short edge ≥320.
 
 #### Parameters
 
 | Parameter | Type         |
 | --------- | ------------ |
 | `bytes`   | `Uint8Array` |
+| `model`   | `string`     |
 
 #### Returns
 
@@ -352,7 +353,7 @@ hydration.
 
 ```ts
 type MediaReferenceReader = Readonly<{
-  read: (reference) => Promise<MediaReferenceBytes>;
+  read: (reference, model) => Promise<MediaReferenceBytes>;
 }>;
 ```
 
@@ -635,26 +636,6 @@ Decode a viewer long-edge size within the supported pixel bounds.
 
 ---
 
-### MAX\_REFERENCE\_COUNT
-
-```ts
-const MAX_REFERENCE_COUNT: 4 = 4;
-```
-
-Maximum reference files in one generation request.
-
----
-
-### MAX\_REFERENCE\_DIMENSION
-
-```ts
-const MAX_REFERENCE_DIMENSION: 512 = 512;
-```
-
-Maximum reference width and height sent to inference, in pixels.
-
----
-
 ### MAX\_REFERENCE\_BYTES
 
 ```ts
@@ -770,6 +751,7 @@ const mediaGenerationSelectionSchema: ZodObject<
       ZodArray<
         ZodObject<
           {
+            computerId: ZodOptional<ZodString>;
             path: ZodString;
             role: ZodOptional<
               ZodEnum<{
@@ -788,7 +770,7 @@ const mediaGenerationSelectionSchema: ZodObject<
 >;
 ```
 
-App selections contain paths; the host supplies the admitted Computer.
+A reference may select another Computer; identity never grants access.
 
 ---
 
@@ -942,6 +924,7 @@ const mediaModelInputSchema: ZodLazy<
           own: "own";
         }>;
         maxDimension: ZodNullable<ZodNumber>;
+        maxDimensionDocumented: ZodBoolean;
         defaultWidth: ZodNumber;
         defaultHeight: ZodNumber;
         steps: ZodEnum<{
@@ -964,6 +947,17 @@ Media's provider catalog: Workers AI images plus gateway image and video models.
 
 ---
 
+### MAX\_REFERENCE\_COUNT
+
+```ts
+const MAX_REFERENCE_COUNT: 16 = 16;
+```
+
+Schema ceiling for reference lists: the largest per-model limit. Each model's
+own `maxReferences` / `maxReferenceImages` is enforced after parsing.
+
+---
+
 ### mediaVideoModelIdSchema
 
 ```ts
@@ -1100,6 +1094,7 @@ const mediaVideoSchema: ZodLazy<ZodReadonly<ZodObject<{
      ultrawide: "21:9";
      ultratall: "9:21";
   }>;
+  supportsAudio: ZodBoolean;
   defaultGenerateAudio: ZodNullable<ZodBoolean>;
   referenceRoles: ZodReadonly<ZodArray<ZodEnum<{
      first: "first-frame";
@@ -1175,6 +1170,7 @@ const mediaModelSchema: ZodReadonly<ZodObject<{
         own: "own";
      }>;
      maxDimension: ZodNullable<ZodNumber>;
+     maxDimensionDocumented: ZodBoolean;
      defaultWidth: ZodNumber;
      defaultHeight: ZodNumber;
      steps: ZodEnum<{
@@ -1215,6 +1211,7 @@ const mediaModelSchema: ZodReadonly<ZodObject<{
         ultrawide: "21:9";
         ultratall: "9:21";
      }>;
+     supportsAudio: ZodBoolean;
      defaultGenerateAudio: ZodNullable<ZodBoolean>;
      referenceRoles: ZodReadonly<ZodArray<ZodEnum<...>>>;
      maxReferenceImages: ZodNumber;
@@ -1246,6 +1243,16 @@ const USD_PER_1K_NEURONS: 0.011 = 0.011;
 
 Published Workers AI image rate: $0.011 per 1,000 neurons.
 
+---
+
+### MAX\_REFERENCE\_DIMENSION
+
+```ts
+const MAX_REFERENCE_DIMENSION: 512 = 512;
+```
+
+Maximum long edge for image-model references, in pixels.
+
 ## Functions
 
 ### estimateImageNeurons()
@@ -1328,7 +1335,7 @@ function validateMediaGenerationSelection(
 ): Readonly<Omit<MediaGenerationSettings, "references"> & object>;
 ```
 
-Validate path-only selections without inventing a Computer identity.
+Validate selections without granting Computer authority.
 
 #### Parameters
 
@@ -1546,6 +1553,7 @@ function listMediaModels(): readonly Readonly<{
     transport: "json" | "multipart";
     dimensions: "none" | "own";
     maxDimension: number | null;
+    maxDimensionDocumented: boolean;
     defaultWidth: number;
     defaultHeight: number;
     steps: "steps" | "num_steps" | "fixed";
@@ -1570,6 +1578,7 @@ function listMediaModels(): readonly Readonly<{
     defaultResolution: "480p" | "720p" | "768p" | "1080p" | "4k";
     defaultAspectRatio:
       "16:9" | "4:3" | "1:1" | "3:4" | "9:16" | "21:9" | "9:21";
+    supportsAudio: boolean;
     defaultGenerateAudio: boolean | null;
     referenceRoles: readonly ("first-frame" | "last-frame" | "reference")[];
     maxReferenceImages: number;
@@ -1594,23 +1603,24 @@ readonly `Readonly`\<\{ `id`: `string`; `label`: `string`; `kind`: `"image"` \|
 `outputFormats`: readonly (`"png"` \| `"jpeg"` \| `"webp"`)[];
 `maxPromptLength`: `number`; `input`: `Readonly`\<\{ `transport`: `"json"` \|
 `"multipart"`; `dimensions`: `"none"` \| `"own"`; `maxDimension`: `number` \|
-`null`; `defaultWidth`: `number`; `defaultHeight`: `number`; `steps`: `"steps"`
-\| `"num_steps"` \| `"fixed"`; `maxSteps`: `number` \| `null`; `defaultSteps`:
-`number` \| `null`; `referenceField`: `string` \| `null`; `maxReferences`:
-`number`; \}\>; `sizes`: readonly `string`[] \| `null`; `video`: \|
-`Readonly`\<\{ `minSeconds`: `number`; `maxSeconds`: `number`; `defaultSeconds`:
-`number`; `durations`: readonly `number`[]; `provider`: `"seedance"` \| `"veo"`
-\| `"minimax"`; `formats`: readonly `Readonly`\<\{ `resolution`: `"480p"` \|
-`"720p"` \| `"768p"` \| `"1080p"` \| `"4k"`; `aspectRatio`: `"16:9"` \| `"4:3"`
-\| `"1:1"` \| `"3:4"` \| `"9:16"` \| `"21:9"` \| `"9:21"`; `width`: `number`;
-`height`: `number`; \}\>[]; `defaultResolution`: `"480p"` \| `"720p"` \|
-`"768p"` \| `"1080p"` \| `"4k"`; `defaultAspectRatio`: `"16:9"` \| `"4:3"` \|
-`"1:1"` \| `"3:4"` \| `"9:16"` \| `"21:9"` \| `"9:21"`; `defaultGenerateAudio`:
-`boolean` \| `null`; `referenceRoles`: readonly (`"first-frame"` \|
-`"last-frame"` \| `"reference"`)[]; `maxReferenceImages`: `number`;
-`referenceResolutions`: readonly (`"480p"` \| `"720p"` \| `"768p"` \| `"1080p"`
-\| `"4k"`)[]; `prices`: readonly `Readonly`\<\{ `resolution`: `"480p"` \|
-`"720p"` \| `"768p"` \| `"1080p"` \| `"4k"`; `silentMilliunitsPerSecond`:
+`null`; `maxDimensionDocumented`: `boolean`; `defaultWidth`: `number`;
+`defaultHeight`: `number`; `steps`: `"steps"` \| `"num_steps"` \| `"fixed"`;
+`maxSteps`: `number` \| `null`; `defaultSteps`: `number` \| `null`;
+`referenceField`: `string` \| `null`; `maxReferences`: `number`; \}\>; `sizes`:
+readonly `string`[] \| `null`; `video`: \| `Readonly`\<\{ `minSeconds`:
+`number`; `maxSeconds`: `number`; `defaultSeconds`: `number`; `durations`:
+readonly `number`[]; `provider`: `"seedance"` \| `"veo"` \| `"minimax"`;
+`formats`: readonly `Readonly`\<\{ `resolution`: `"480p"` \| `"720p"` \|
+`"768p"` \| `"1080p"` \| `"4k"`; `aspectRatio`: `"16:9"` \| `"4:3"` \| `"1:1"`
+\| `"3:4"` \| `"9:16"` \| `"21:9"` \| `"9:21"`; `width`: `number`; `height`:
+`number`; \}\>[]; `defaultResolution`: `"480p"` \| `"720p"` \| `"768p"` \|
+`"1080p"` \| `"4k"`; `defaultAspectRatio`: `"16:9"` \| `"4:3"` \| `"1:1"` \|
+`"3:4"` \| `"9:16"` \| `"21:9"` \| `"9:21"`; `supportsAudio`: `boolean`;
+`defaultGenerateAudio`: `boolean` \| `null`; `referenceRoles`: readonly
+(`"first-frame"` \| `"last-frame"` \| `"reference"`)[]; `maxReferenceImages`:
+`number`; `referenceResolutions`: readonly (`"480p"` \| `"720p"` \| `"768p"` \|
+`"1080p"` \| `"4k"`)[]; `prices`: readonly `Readonly`\<\{ `resolution`: `"480p"`
+\| `"720p"` \| `"768p"` \| `"1080p"` \| `"4k"`; `silentMilliunitsPerSecond`:
 `number`; `audioMilliunitsPerSecond`: `number`; \}\>[]; \}\> \| `null`; \}\>[]
 
 ---
@@ -1630,6 +1640,7 @@ function getMediaModel(id):
         transport: "json" | "multipart";
         dimensions: "none" | "own";
         maxDimension: number | null;
+        maxDimensionDocumented: boolean;
         defaultWidth: number;
         defaultHeight: number;
         steps: "steps" | "num_steps" | "fixed";
@@ -1655,6 +1666,7 @@ function getMediaModel(id):
         defaultResolution: "480p" | "720p" | "768p" | "1080p" | "4k";
         defaultAspectRatio:
           "16:9" | "4:3" | "1:1" | "3:4" | "9:16" | "21:9" | "9:21";
+        supportsAudio: boolean;
         defaultGenerateAudio: boolean | null;
         referenceRoles: readonly ("first-frame" | "last-frame" | "reference")[];
         maxReferenceImages: number;
@@ -1686,23 +1698,24 @@ Find a model by provider identifier, returning undefined when it is absent.
 `outputFormats`: readonly (`"png"` \| `"jpeg"` \| `"webp"`)[];
 `maxPromptLength`: `number`; `input`: `Readonly`\<\{ `transport`: `"json"` \|
 `"multipart"`; `dimensions`: `"none"` \| `"own"`; `maxDimension`: `number` \|
-`null`; `defaultWidth`: `number`; `defaultHeight`: `number`; `steps`: `"steps"`
-\| `"num_steps"` \| `"fixed"`; `maxSteps`: `number` \| `null`; `defaultSteps`:
-`number` \| `null`; `referenceField`: `string` \| `null`; `maxReferences`:
-`number`; \}\>; `sizes`: readonly `string`[] \| `null`; `video`: \|
-`Readonly`\<\{ `minSeconds`: `number`; `maxSeconds`: `number`; `defaultSeconds`:
-`number`; `durations`: readonly `number`[]; `provider`: `"seedance"` \| `"veo"`
-\| `"minimax"`; `formats`: readonly `Readonly`\<\{ `resolution`: `"480p"` \|
-`"720p"` \| `"768p"` \| `"1080p"` \| `"4k"`; `aspectRatio`: `"16:9"` \| `"4:3"`
-\| `"1:1"` \| `"3:4"` \| `"9:16"` \| `"21:9"` \| `"9:21"`; `width`: `number`;
-`height`: `number`; \}\>[]; `defaultResolution`: `"480p"` \| `"720p"` \|
-`"768p"` \| `"1080p"` \| `"4k"`; `defaultAspectRatio`: `"16:9"` \| `"4:3"` \|
-`"1:1"` \| `"3:4"` \| `"9:16"` \| `"21:9"` \| `"9:21"`; `defaultGenerateAudio`:
-`boolean` \| `null`; `referenceRoles`: readonly (`"first-frame"` \|
-`"last-frame"` \| `"reference"`)[]; `maxReferenceImages`: `number`;
-`referenceResolutions`: readonly (`"480p"` \| `"720p"` \| `"768p"` \| `"1080p"`
-\| `"4k"`)[]; `prices`: readonly `Readonly`\<\{ `resolution`: `"480p"` \|
-`"720p"` \| `"768p"` \| `"1080p"` \| `"4k"`; `silentMilliunitsPerSecond`:
+`null`; `maxDimensionDocumented`: `boolean`; `defaultWidth`: `number`;
+`defaultHeight`: `number`; `steps`: `"steps"` \| `"num_steps"` \| `"fixed"`;
+`maxSteps`: `number` \| `null`; `defaultSteps`: `number` \| `null`;
+`referenceField`: `string` \| `null`; `maxReferences`: `number`; \}\>; `sizes`:
+readonly `string`[] \| `null`; `video`: \| `Readonly`\<\{ `minSeconds`:
+`number`; `maxSeconds`: `number`; `defaultSeconds`: `number`; `durations`:
+readonly `number`[]; `provider`: `"seedance"` \| `"veo"` \| `"minimax"`;
+`formats`: readonly `Readonly`\<\{ `resolution`: `"480p"` \| `"720p"` \|
+`"768p"` \| `"1080p"` \| `"4k"`; `aspectRatio`: `"16:9"` \| `"4:3"` \| `"1:1"`
+\| `"3:4"` \| `"9:16"` \| `"21:9"` \| `"9:21"`; `width`: `number`; `height`:
+`number`; \}\>[]; `defaultResolution`: `"480p"` \| `"720p"` \| `"768p"` \|
+`"1080p"` \| `"4k"`; `defaultAspectRatio`: `"16:9"` \| `"4:3"` \| `"1:1"` \|
+`"3:4"` \| `"9:16"` \| `"21:9"` \| `"9:21"`; `supportsAudio`: `boolean`;
+`defaultGenerateAudio`: `boolean` \| `null`; `referenceRoles`: readonly
+(`"first-frame"` \| `"last-frame"` \| `"reference"`)[]; `maxReferenceImages`:
+`number`; `referenceResolutions`: readonly (`"480p"` \| `"720p"` \| `"768p"` \|
+`"1080p"` \| `"4k"`)[]; `prices`: readonly `Readonly`\<\{ `resolution`: `"480p"`
+\| `"720p"` \| `"768p"` \| `"1080p"` \| `"4k"`; `silentMilliunitsPerSecond`:
 `number`; `audioMilliunitsPerSecond`: `number`; \}\>[]; \}\> \| `null`; \}\> \|
 `undefined`
 

package/docs/api/server.md

@@ -53,6 +53,14 @@ readonly provider: MediaProviderDiagnostic | undefined;
 
 Safe provider facts only; the original cause remains private.
 
+##### customerCharge
+
+```ts
+readonly customerCharge: "none" | "unknown";
+```
+
+Unknown unless the execution owner confirmed zero-unit settlement.
+
 ##### stage
 
 ```ts
@@ -780,9 +788,10 @@ Private cause plus an independently decoded, safe provider diagnostic.
 
 #### Type Declaration
 
-| Name        | Type                      | Description                                                         |
-| ----------- | ------------------------- | ------------------------------------------------------------------- |
-| `provider?` | `MediaProviderDiagnostic` | Safe provider facts, when the failure came from provider transport. |
+| Name              | Type                      | Description                                                               |
+| ----------------- | ------------------------- | ------------------------------------------------------------------------- |
+| `provider?`       | `MediaProviderDiagnostic` | Safe provider facts, when the failure came from provider transport.       |
+| `customerCharge?` | `"none"`                  | Confirmed zero-unit customer settlement, never an upstream billing claim. |
 
 ---
 
@@ -1457,7 +1466,7 @@ type MediaServiceHost = Readonly<{
   destination: Readonly<{
      authorize: (path) => Promise<void>;
      write: (path, bytes) => Promise<void>;
-     readReference?: (reference) => Promise<MediaReferenceBytes>;
+     readReference?: (reference, model) => Promise<MediaReferenceBytes>;
   }>;
   onFailure?: (error) => Response | undefined;
 }> &
@@ -1554,6 +1563,7 @@ const mediaImageBindingInputSchema: ZodObject<{
      }>>;
      generateAudio: ZodOptional<ZodBoolean>;
      references: ZodOptional<ZodArray<ZodObject<{
+        computerId: ZodOptional<ZodString>;
         path: ZodString;
         role: ZodOptional<ZodEnum<{
            first: ...;
@@ -1652,6 +1662,7 @@ const mediaBindingGenerationSchema: ZodDiscriminatedUnion<[ZodObject<{
      }>>;
      generateAudio: ZodOptional<ZodBoolean>;
      references: ZodOptional<ZodArray<ZodObject<{
+        computerId: ZodOptional<...>;
         path: ZodString;
         role: ZodOptional<...>;
      }, $strict>>>;
@@ -1749,7 +1760,7 @@ const mediaBindingCallSchema: ZodDiscriminatedUnion<[ZodObject<{
 }, $strict>], "operation">;
 ```
 
-Maintained MEDIA method grammar; guest input carries no principal or Computer.
+Maintained MEDIA grammar; reference selectors carry no Computer authority.
 
 ---
 
@@ -1947,6 +1958,31 @@ Decode relative service generation input. Identity comes from the host.
 
 ## Functions
 
+### estimateMediaModel()
+
+```ts
+function estimateMediaModel(model): object;
+```
+
+Quote the catalog defaults through the exact estimator used before dispatch.
+
+#### Parameters
+
+| Parameter | Type                                |
+| --------- | ----------------------------------- |
+| `model`   | [`MediaModel`](index.md#mediamodel) |
+
+#### Returns
+
+| Name             | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Description                                                       |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `kind`           | `"estimate"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | An indicative quote, not an admitted generation receipt.          |
+| `basis`          | `"provider-cost"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Provider cost before the host's billing policy.                   |
+| `settings`       | `Readonly`\<\{ `model`: `string`; `prompt`: `string`; `width`: `number`; `height`: `number`; `steps?`: `number`; `durationSeconds?`: `number`; `resolution?`: `"480p"` \| `"720p"` \| `"768p"` \| `"1080p"` \| `"4k"`; `aspectRatio?`: `"16:9"` \| `"4:3"` \| `"1:1"` \| `"3:4"` \| `"9:16"` \| `"21:9"` \| `"9:21"`; `generateAudio?`: `boolean`; `references?`: readonly `Readonly`\<\{ `computerId`: `string`; `path`: `string`; `role?`: `"first-frame"` \| `"last-frame"` \| `"reference"`; \}\>[]; \}\> | Catalog defaults, a one-character prompt and no references.       |
+| `costMilliunits` | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Estimated provider milliunits of a cent for these exact settings. |
+
+---
+
 ### mediaUnits()
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/darkroom",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Media generation, durable output retention and provenance with host-owned authority and billing",
   "type": "module",
@@ -59,7 +59,7 @@
     "exifreader": "4.46.0",
     "@fungi.computer/ts-webp": "0.1.6",
     "@xmldom/xmldom": "0.9.12",
-    "@fungi.computer/agar": "0.4.0",
+    "@fungi.computer/agar": "0.6.0",
     "@fungi.computer/capnweb": "0.12.0"
   },
   "devDependencies": {